Feature proposal: product-session attribution and observability envelope for subagent providers

[jeremy9682]

Feature proposal: product-session attribution and observability envelope for subagent providers

Summary

@deepseek-ai/dsh-subagent-codex is a one-shot bridge: each run starts
codex app-server --stdio, creates one ephemeral thread, submits one task, and
returns only the final answer. What it does not retain is any durable
pointer back to the product's own session artifact. We run a local
governance layer (agent-run, a small open wrapper around the same CLIs) whose
whole value is exactly that pointer, and we believe the gap is worth closing in
DSH itself — as an opt-in plugin, not a change to the provider contract.

What we verified in the current source

• packages/subagent/subagent-codex/src/wire.ts keeps threadId/turnId as
  private protocol state (private threadId: string | undefined); nothing
  writes them to the parent Session.
• The package README states the same as a deliberate limitation: "Final text
  only — reasoning, commentary, intermediate messages, tool traffic, usage,
  stderr, and workspace diffs remain product-local"; the ephemeral thread id and
  turn id "are never persisted in the parent Session"; there is "no wall-clock
  timeout".
• So after a run, the durable log has tool/call + final tool/result, but no
  session_ref pointing at
  ~/.codex/sessions/2026/08/14/rollout-*.jsonl. Reconstructing "what did the
  Codex child actually do" from the DSH session alone is impossible.

What our wrapper returns for the same runs (real envelopes)

One read-only smoke task through codex exec --json, and one through Cursor's
CLI, both unattended:

{
  "run_id": "a7385536-…",
  "provider": "codex",
  "seat": "codex-smoke-test",
  "exit_code": 0,
  "failure_class": "none",
  "duration_ms": 55268,
  "session_id": "01a000ff-…",
  "session_ref": "~/.codex/sessions/2026/08/14/rollout-2026-08-14T11-58-35-….jsonl",
  "session_status": "attributed-stream-json",
  "model": "gpt-5.6-terra",
  "model_observed": "gpt-5.6-terra"
}

{
  "provider": "cursor",
  "seat": "founder-smoke-cursor",
  "session_ref": "~/.cursor/chats/6a7822…/0890528f-….jsonl/store.db",
  "session_status": "attributed-correlated-artifacts",
  "model": "auto",
  "model_observed": "cursor-grok-4.5-high-fast",
  "model_family": "xai"
}

The attribution is a before/after fingerprint of the product's session root:
exactly one changed artifact → attributed-*; zero → not-observed; several →
ambiguous-concurrent-artifacts. model_observed is parsed from the provider's
own events, so an auto route that silently lands on a different model is
detected. Idle gaps during model reasoning are bounded by a per-provider idle
timeout distinct from the total deadline.

Proposal: an opt-in observability plugin, on existing extension points

1. Durable pointer. A new log-only SessionEvent (declaration-merged into
   SessionEventMap) carrying { provider, runId, sessionRef, sessionStatus, modelObserved, failureClass }, appended when the outer tool result settles.
   The pointer becomes part of the durable log, consistent with the
   "model-visible ⟺ logged" convention (the pointer itself is log-only).
2. Attribution. A tools/result observer takes before/after fingerprints of
   configurable provider session roots (same roots-per-provider shape our
   manifest uses) and fills sessionRef/sessionStatus.
3. Idle timeout. A configurable cancel policy wrapping the run — the
   current "caller cancels" stance is documented as deliberate, so this stays
   opt-in configuration rather than a default change.
4. Model attribution. Parse the provider's terminal events for the observed
   model before the provider discards them, and record it in the same event.

No changes are required to dsh-subagent's result contract or to the app-server
wire protocol. Real-composition tests and the persistence-catalog entry would
ship with the plugin, per the repo's testing policy.

Why it matters

• Post-hoc review. A reviewer can open the exact product transcript a
  subagent produced, instead of only its final answer.
• Model-route verification. auto/undisclosed routes that land on an
  unexpected model become visible in the session log.
• Failure forensics. failure_class (context-window, idle, total, provider
  failure) survives into the log instead of collapsing into one error string.
• Same mechanics extend per product. Cursor, Claude Code, and Grok each need
  only a root list + adapter, not a new provider.

Prior art in this repo's discussions (checked 2026-08-14)

Searched existing discussions before filing; none covers product-session
attribution for subagent providers. Adjacent work, each with a different scope:

• #1365 DSH Trust Layer —
  verification receipts and hash chains over DSH's own session events. It never
  sees the child product's local traffic, because subagent-codex returns final
  text only — exactly the gap this proposal closes.
• #1007 dsh-plugin-langfuse —
  exports the parent session as OTel traces; same blind spot for child-internal
  activity, and no pointer to the product's own transcript artifact.
• #1215 Windows Codex CLI integration —
  wire/CLI seams for Windows support; not run attribution.
• #1202 subagent stale UI states —
  a lifecycle UI bug, not observability of external runs.
• #208,
  #504,
  #505,
  #518,
  #881,
  #1211 —
  Codex-as-LLM-provider community plugins (OAuth/subscription). Orthogonal:
  they make Codex a model route; this proposal attributes external subagent
  runs after the fact.

Happy to open a PR for the plugin if this direction is welcome. Filed for
discussion before implementation per the project's contribution guidance.

[CHXZAVARKA]

The durable product-session pointer proposed here would solve the immediate audit gap. I would also treat it as the first optional layer of a broader external-subagent lifecycle contract.

The current final-text provider can remain the baseline. Providers could advertise extra capabilities when they support them:

• durable external session reference
• progress events
• continuation or follow-up
• user input and approval requests
• cancellation acknowledgement
• usage and artifact references

Instead of making every provider implement these methods, start() could return a run handle with a capability set. The parent would only offer continuation or approval routing when the handle supports it. Existing one-shot ACP, Codex, and Claude Code providers would keep working unchanged.

For Codex, the bridge already observes thread and turn identifiers internally. Persisting an opaque reference would let a later delegation continue the same product session when the backend allows it. Progress and approval events could enter the parent as typed subagent events rather than being collapsed into the final tool result.

I would keep this separate from the attribution plugin proposed above:

1. Attribution records where a run happened and how to inspect it later.
2. The optional lifecycle contract controls a run while it is happening.

A small first slice would persist the external session reference, expose provider capabilities, and support cancellation acknowledgement. Continuation and approval forwarding could follow without changing the result contract for final-text-only providers.

[Electricitysheep]

子代理 provider 的可观测性（session 归属/观测包络）——子代理是黑盒时排障很痛苦，归属到 product-session + 观测包络能打通全链路。

和 #1498（provider 配置）、#1442（子代理模型选择）一起，子代理体系正在完善。第 9 章子代理配置可作参考：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/09-mcp-subagent-workflow.md

[jeremy9682]

Field report: the plugin sketch is now boot-tested

A minimal implementation of steps 1–2 from the proposal was built and mounted
in a real composition (isolated DSH_HOME, dsh --profile headless --patch …,
npm 0.1.0-rc.6). Evidence from three runs:

1. Plugin boots and its tools/pre-execute + tools/result observers fire per
   tracked tool call (journal lines per call).
2. Attribution classification works end-to-end: a tracked call that created one
   artifact in a watched root produced
   {"sessionStatus":"attributed-single-artifact","sessionRef":"/path/to/artifact"};
   a no-change call produced not-observed.
3. A sibling tool ported from opencodex (cursor_delegate → cursor-agent CLI)
   verified the same composition pattern: DSH → tool → external CLI → answer.

New finding that sharpens the proposal: the durable log-only event (step 1)
is not currently reachable from an out-of-tree plugin. Session.append() has no
ignorable marker, and the generated
@deepseek-ai/dsh-session/known-event-types module states: "Downstream
(out-of-repo) plugin events are outside this list by construction; a
registration surface for them is deferred until such a consumer exists."
So any persistence read would refuse a session log containing a plugin-owned
event type. The upstream work this proposal implies is therefore two precise
items: (a) a downstream event-type registration surface, and (b) append-time
ignorable control. Until then the file journal (pointers only) is the working
fallback.

Happy to open the PR for either half, or both, if this direction is welcome.

[CHXZAVARKA]

Thanks for boot-testing this and publishing the sketch. The custom-event finding identifies the upstream seam more clearly than the original proposal did.

I would split the work into three pieces:

1. Core support for durable events owned by external plugins.
2. The attribution plugin built on that support.
3. A separate provider-lifecycle proposal for progress, continuation, approvals, and cancellation.

For the first piece, ignorable needs to be durable in the event envelope. It cannot depend only on a plugin being registered when the log is read. Otherwise uninstalling or downgrading a plugin can make an existing session unreadable.

The registration contract should probably include a namespaced event type, owner, schema version, and decoder. Unknown ignorable events should survive copy, migration, and export even when projections skip them. Conflicting registrations should fail before the first append.

The regression test I would want is:

1. Install a plugin and append its event.
2. Stop the session and remove the plugin.
3. Resume and continue the session successfully.
4. Reinstall the plugin and recover its projection from the preserved event.

Your file-journal fallback looks appropriate for the prototype. Moving the pointer into the session log should wait until the missing-plugin path is safe.

[jeremy9682]

Code for the boot-tested sketch is now public, tagged for discoverability:

https://github.com/jeremy9682/dsh-observability (dsh-plugin topic)

• dsh-codex-observability — attribution envelope via tools/pre-execute snapshot + tools/result diff, journal fallback (pointers only).
• dsh-tool-cursor — cursor_delegate tool ported from the opencodex cursor.ts reference (CLI delegation on the local Cursor subscription).
• bin/dsh-run-attributed.mjs — standalone CLI with the same fingerprint + envelope + three-tier timeout, usable without DSH.

Both packages install via dsh plugin --profile web add github:jeremy9682/dsh-observability (prepare-build; pnpm's allowBuilds gate applies on first add).

[jeremy9682]

Thanks for taking the time to spec this out — the three-piece split matches how we now see it too: (1) core support for durable events owned by external plugins, (2) the attribution plugin built on it, (3) a separate provider-lifecycle proposal. Agreed that (3) should not be mixed into this thread.

One thing our source re-check sharpened: the read side already implements the envelope-marker contract you describe. In the current tree:

• SessionEvent already carries ignorable?: true in the envelope (packages/core/session/src/types.ts), and both persistence backends store it (a dedicated SQLite column; whole-object JSONL).
• The read path already refuses an unknown type without the marker and already skips-and-preserves an unknown type with it (assertEventsSupported in packages/session/session-persistence/src/coordinator.ts).
• Adding an ordinary event type does not bump SESSION_FORMAT_VERSION — the per-event ignorable guard is the documented mechanism for vocabulary growth.
• The projection registry (ctx.sessionProjections) already provides register/conflict-refusal/cold-fold-recovery, which is exactly what the fourth regression step needs.

So the actual gap in the harness is narrow, and piece (1) becomes two precise changes plus wiring:

(a) Append-side ignorable control. Session.append(type, data, ...opts) currently never writes the marker, so a plugin can append its own type today but the resulting log is refused once the plugin is gone. Proposed:

append<T extends SessionEventType>(
  type: T,
  data: SessionEventMap[T],
  ...opts: T extends SurfaceEventType
    ? [opts: SurfaceIntent & { readonly ignorable?: false }]
    : [opts?: { readonly ignorable?: true }]
): SessionEvent<T>

Runtime rules: surface types may never set ignorable; a type outside KNOWN_SESSION_EVENT_TYPES (downstream) must be both registered and marked ignorable: true; known non-surface types may carry the marker (inert). The marker is written into the envelope, so it is durable in both backends with no format bump.

(b) Downstream registration surface. A small host-plane registry service (new package, mirroring ctx.sessionProjections), e.g.:

ctx.sessionEvents.register({
  type: 'dsh-codex-observability/run-attributed', // namespaced namespace/name
  owner: 'dsh-codex-observability',
  schemaVersion: 1,
  decode: (data: JsonValue) => unknown,           // throws on invalid data
}): () => void

Conflict rules — all enforced at registration time, i.e. before the first append: un-namespaced type → refuse; type shadowing a KNOWN_SESSION_EVENT_TYPES member → refuse; same type, different owner → refuse; same owner, different schemaVersion → refuse; identical re-registration → refcounted disposers (the sessionProjections precedent). Append consults the registry through the existing store→session attachment channel (same path the append-publication hooks use), so Session stays store-agnostic and an unregistered downstream type fails loudly at the append site.

Acceptance test — your four steps verbatim, run against both persistence backends (JSONL and SQLite):

1. Install the plugin and append its event (marker present in the envelope).
2. Stop the session and remove the plugin.
3. Resume and continue the session successfully — the unknown event is skipped but preserved.
4. Reinstall the plugin and recover its projection from the preserved event (re-register + cold fold).

Plus an export-survival test: a log containing an unknown ignorable event round-trips through copy/export without losing the event.

Our current plugins (dsh-codex-observability, dsh-tool-cursor at github.com/jeremy9682/dsh-observability) are the concrete consumer of this surface; the file journal stays as the prototype fallback exactly as you said, and the durable in-log pointer waits for the missing-plugin path to be safe.

We are happy to open the PR for (a) + (b) together. Two design points we'd flag for maintainer review before we start: whether the registry should live on the host plane or the agent plane (we lean host, matching sessionProjections), and whether the registered decode should also drive export rendering or stay advisory. If this direction is welcome, we'll start the branch this week.

[jeremy9682]

配套实现仓库已进入社区插件目录：awesome-dsh-plugin 收录 PR https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/274（dsh-observability，含中文 README）。文件 journal 的过渡方案可安装：dsh plugin --profile web add github:jeremy9682/dsh-observability。上游注册面/ignorable 两项仍按本讨论的实施规格等待官方方向。