feat(agents): OCG-backed long-term agent memory + feedback links

[NicholasDCole]

Ports the SDK side of the agentspan "OCG-backed agent memory" feature (agentspan-ai/agentspan#298) to the TypeScript/JavaScript SDK. The server-side compiler that consumes this wire contract lives in conductor-oss/conductor (agentspan-server: LongTermMemoryConfig.java, AgentConfig.longTermMemory / feedbackSink).

What was ported

• OCGMemoryStore (src/agents/ocg-memory.ts) — HTTP adapter over the OCG BFF: search (POST /api/v1/memories/search), add (POST /api/v1/memories), delete, listAll, clear, and feedbackLinks (POST /api/v1/memories/{key}/feedback-links). Bearer auth via Authorization: Bearer <token>.
• Agent params (src/agents/agent.ts) — semanticMemory (an OCGMemoryStore, or a SemanticMemory wrapping one), memorySummaryModel, feedbackSink.
• Serializer emission (src/agents/serializer.ts) — the most important piece; the server only activates the feature when this is emitted:
  • longTermMemory: {ocgUrl, credential, agent, user, scope, maxResults, summaryModel}, camelCase, nulls omitted. credential is a server-resolvable secret NAME (default OCG_PUBLIC_KEY), never the raw client token. summaryModel falls back to the agent's own model. Emitted only for OCG-backed stores.
  • feedbackSink: {taskName: "<agent>_feedback_sink"}, emitted when the sink is set.
• Runtime worker (src/agents/runtime.ts) — registers the <agent>_feedback_sink worker so the compiled server path can hand the distilled summary + signed good/bad capability URLs to the local feedbackSink for out-of-band human delivery. Best-effort; never fails the run. The capability URLs are never surfaced to the agent's LLM.
• Helpers — FeedbackEvent, MemorySummary, buildMemorySummarizer, exported via src/agents/index.ts.
• Example — examples/agents/118-ocg-memory.ts, mirroring the Python 118_ocg_memory.py.

JS/TS-specific adaptations

• Async store. JS fetch is async-only, so OCGMemoryStore methods return Promises and it does not implement the SDK's synchronous MemoryStore interface (that stays keyword-search in-memory). The serializer reads the store structurally (duck-typed on ocgUrl), so both a bare OCGMemoryStore and a SemanticMemory wrapping one are supported.
• No client-side pre/post-run retrieval/save hooks. The Python runtime.py wraps server execution with client-side memory-injection and conversation-save hooks. In this SDK, AgentRuntime.run() delegates the entire agent loop to the server via POST /agent/start, and run() sends the same serialized config — so the server's compiled longTermMemory steps (retrieval pre-loop, distill/save/feedback post-loop) drive memory on both the deployed and run() paths. Re-implementing those hooks client-side would duplicate the server's work and, given the sync/async MemoryStore mismatch above, does not map cleanly — so it is omitted. The one runtime piece that does map cleanly (and is ported) is the feedback_sink worker registration.
• FeedbackEvent fields are camelCase (memoryKey, goodUrl, ...); the worker maps the server's snake_case task input.
• Naming follows this SDK's camelCase conventions (semanticMemory, memorySummaryModel, feedbackSink, maxResults).

Tests

New/updated jest tests (src/agents/__tests__/ocg-memory.test.ts, serializer.test.ts):

• Store: url normalization, blank-arg validation, add posts value (not string_value/confidence) with agent/user, search folds the good/bad signal into content, feedbackLinks route, bearer header, non-2xx → AgentAPIError.
• Serializer: OCG-backed → longTermMemory + feedbackSink; SemanticMemory-wrapped store; absent memory → no keys; summaryModel fallback; plain non-OCG memory emits nothing.
• Runtime: feedback_sink worker rebuilds a FeedbackEvent and calls the sink; swallows sink failures; not registered without a sink.

Typecheck clean for all touched files. Lint clean (one pre-existing warning in untouched agent.ts).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 93.05302% with 38 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/agents/ocg-memory.ts	90.05%	38 Missing ⚠️

Flag	Coverage Δ
integration-v4-sm	41.26% <9.32%> (-0.53%)	⬇️
integration-v5-sdkdev	43.63% <9.32%> (-0.65%)	⬇️
unit	73.71% <92.68%> (+0.35%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/agents/agent.ts	92.22% <100.00%> (+0.45%)	⬆️
src/agents/memory.ts	95.42% <100.00%> (+0.01%)	⬆️
src/agents/runtime.ts	67.60% <100.00%> (+0.84%)	⬆️
src/agents/serializer.ts	93.06% <100.00%> (+1.00%)	⬆️
src/agents/ocg-memory.ts	90.05% <90.05%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.