Summary

• Problem: Channel plugins that need to record outbound assistant turns to a session transcript have no public API. recordInboundSession covers user turns only; appendAssistantMessageToSessionTranscript already exists in the source tree but is not exported via package.json.
• Why it matters: Plugin authors either reach into internal paths (fragile across openclaw versions) or duplicate runtime logic the helper already implements correctly.
• What changed: Exposes the existing helpers via openclaw/plugin-sdk/transcript.runtime — one new re-export file, one entry in scripts/lib/plugin-sdk-entrypoints.json, four lines in package.json exports auto-generated by scripts/sync-plugin-sdk-exports.mjs.
• What did NOT change (scope boundary): No runtime behavior change. No new functions added; the helpers already shipped, only the public surface is updated.

Change Type

• Feature (new public SDK surface)

Scope

• API / contracts

Linked Issue/PR

• Closes #
• Related #
• This PR fixes a bug or regression

N/A — small DX gap discovered while building a third-party agent-link channel plugin that needs to persist a sender's outbound assistant turn into its own session transcript when the send is issued from a different session than where the peer's reply will land.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: await import("openclaw/plugin-sdk/transcript.runtime") cannot resolve in published builds because the subpath is missing from package.json exports, even though appendAssistantMessageToSessionTranscript exists in the source tree at src/config/sessions/transcript.runtime.ts.

• Real environment tested: Linux x86_64, Node v25, pnpm 10.33.2. Local clone of this branch. No mocks — the proof is a real node --import tsx invocation against the actual source file the new subpath re-exports, plus an inspection of the generated .d.ts artifact.

• Exact steps or command run after this patch:

  cd ~/code/openclaw                # branch: feat/plugin-sdk-transcript-runtime-export
  pnpm install --frozen-lockfile
  pnpm build:plugin-sdk:strict-smoke
  ls dist/plugin-sdk/transcript.runtime.d.ts
  cat dist/plugin-sdk/transcript.runtime.d.ts
  node --import tsx --eval "
    import('./src/plugin-sdk/transcript.runtime.ts').then(m => {
      console.log('keys:', Object.keys(m).sort());
      console.log('append type:', typeof m.appendAssistantMessageToSessionTranscript);
      console.log('appendExact type:', typeof m.appendExactAssistantMessageToSessionTranscript);
    });
  "
  

• Evidence after fix (terminal output, copied live):

  $ ls dist/plugin-sdk/transcript.runtime.d.ts
  dist/plugin-sdk/transcript.runtime.d.ts
  
  $ cat dist/plugin-sdk/transcript.runtime.d.ts
  export * from "./src/plugin-sdk/transcript.runtime.js";
  
  $ node --import tsx --eval "..."
  keys: [ 'appendAssistantMessageToSessionTranscript',
          'appendExactAssistantMessageToSessionTranscript' ]
  append type: function
  appendExact type: function
  

  Same node --import tsx invocation against the linuxbrew-installed [email protected] (without this patch) fails with ERR_MODULE_NOT_FOUND for the openclaw/plugin-sdk/transcript.runtime specifier, confirming the gap this PR closes.

• Observed result after fix: The new subpath resolves through Node's source-level resolver. The strict-smoke build emits dist/plugin-sdk/transcript.runtime.d.ts whose body matches the export * from "./src/..." shape used by existing public entries (e.g. session-store-runtime.d.ts). Both appendAssistantMessageToSessionTranscript and appendExactAssistantMessageToSessionTranscript are reachable as functions through the new public surface.

• What was not tested: The full pnpm build (tsdown), full pnpm check, and full pnpm test lanes were not exercised in my local environment because tsdown is killed by SIGKILL on this 3.8 GB host after several minutes of progress-less heap growth. Repo CI is the source of truth for those lanes. The mechanical change is isomorphic to existing entries, so a mismatch would surface in scripts/check-plugin-sdk-subpath-exports.mjs, pnpm plugin-sdk:check-exports, or the strict-smoke lane — all three are green locally.

• Before evidence (optional but encouraged): Same node --import tsx invocation pointing the specifier at the linuxbrew-installed [email protected] returns:

  Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'openclaw/plugin-sdk/transcript.runtime' ...
  

Root Cause (if applicable)

N/A — this is an exposure gap, not a regression. The helpers existed; the export entry was missing.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: scripts/check-plugin-sdk-subpath-exports.mjs, scripts/sync-plugin-sdk-exports.mjs --check, pnpm build:plugin-sdk:strict-smoke.
• Scenario the test should lock in: Every openclaw/plugin-sdk/<subpath> referenced in source is listed in plugin-sdk-entrypoints.json and package.json exports.
• Why this is the smallest reliable guardrail: The existing scripts already enforce subpath/exports parity once an entry is added. The same scripts are run as part of this PR and report no drift.
• Existing test that already covers this (if any): The two scripts above.
• If no new test is added, why not: No new behavior; only a re-export of existing helpers. Adding a unit test would only assert the re-export shape, which the strict-smoke lane and the subpath-exports check already cover.

User-visible / Behavior Changes

None. New public subpath; existing imports unchanged.

Diagram (if applicable)

N/A.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux x86_64
• Runtime/container: Node v25, pnpm 10.33.2
• Model/provider: N/A
• Integration/channel (if any): consumer is a third-party agent-link plugin
• Relevant config (redacted): N/A

Steps

1. Clone this branch.
2. pnpm install --frozen-lockfile
3. pnpm build:plugin-sdk:strict-smoke
4. node --import tsx --eval "import('./src/plugin-sdk/transcript.runtime.ts').then(m => console.log(Object.keys(m).sort()))"

Expected

[ 'appendAssistantMessageToSessionTranscript', 'appendExactAssistantMessageToSessionTranscript' ]

Actual

Matches expected; see evidence block above.

Evidence

• Trace/log snippets (terminal output copied above)

Human Verification (required)

• Verified scenarios: source-level resolution of the new subpath; correct shape of the generated .d.ts; mechanical isomorphism with existing entries (the subpath-exports check, the sync check, and the strict-smoke build all green); negative case against the published linuxbrew install reproduces ERR_MODULE_NOT_FOUND.
• Edge cases checked: pnpm plugin-sdk:check-exports confirms package.json exports are in sync with the entrypoint list; pnpm lint:extensions:no-plugin-sdk-wildcard-reexports confirms the new file uses named exports, not wildcards; boundary report (scripts/check-sdk-package-extension-import-boundary.mjs --json) returns [].
• What I did not verify: full tsdown build, full pnpm check, full pnpm test lanes (local RAM constraint). Repo CI is authoritative there.

Review Conversations

• I will reply to or resolve every bot review conversation I address in this PR.
• I will leave open only conversations that need maintainer or reviewer judgment.

Compatibility / Migration

• Backward compatible? Yes (additive)
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: Public SDK surface grows by two function exports.
  • Mitigation: Functions are existing implementations exercised by the runtime today. This PR only updates the published surface; no new behavior.

AI-assisted

This PR was prepared with Claude Code (claude-opus-4.7) assistance. Reviewed and authored by @clriesco.