Request for direction: Context Continuity Packet metadata for CAP events

[SeCuReDmE-main-dev]

Summary

A comment on the OpenAI Swarm context-continuity discussion pointed to Commonly as a kernel-owned/shared-layer approach to continuity, rather than runtime-attached memory.

That maps closely to Commonly's existing architecture:

• Commonly is the social/kernel layer, not the agent runtime.
• CAP keeps the external runtime surface small.
• AgentMemory already owns durable continuity by (agentName, instanceId).
• Agent events already carry delivery and memory freshness signals.

I would like maintainer direction on whether this pattern should be named explicitly in Commonly as Context Continuity Packet / CCP metadata, or whether maintainers prefer another name, shape, or smaller scope.

Context

The useful distinction from the Swarm thread is not "add another memory system." It is:

continuity should be owned by the shared layer/kernel, not attached to each runtime.

Commonly already seems to be on that side of the design:

• docs/adr/ADR-003-memory-as-kernel-primitive.md
• docs/adr/ADR-004-commonly-agent-protocol.md
• docs/adr/ADR-012-memory-propagation-and-injection.md
• docs/agents/AGENT_RUNTIME.md

The open question is whether external CAP driver authors would benefit from a small named convention for optional continuity metadata at event/message boundaries.

Request For Direction

Which direction would you prefer?

1. No new convention.

   • Existing AgentMemory and CAP docs are enough.

2. Docs-only convention.

   • Document Context Continuity Packet / CCP as optional CAP event metadata.
   • No code or behavior change.

3. Full additive kernel metadata.

   • Attach a computed top-level continuity packet to CAP events.
   • Use existing AgentEvent and AgentMemory state.
   • No new CAP verb, no new memory store, no prompt injection.

4. Rename or reshape the convention.

   • Keep the kernel-owned continuity idea, but choose a different name, field placement, or schema shape.

My preference is option 3, with the name Context Continuity Packet / CCP, because that name has already been useful in organizing this pattern and appears recognizable across adjacent discussions.

PR Timing

I am currently testing a full draft implementation locally. I am opening this issue first so maintainers can give direction before the PR is published.

After the local tests pass, I plan to open a PR linked from this issue. The PR will be an implementation proposal attached to this RFI, not a final maintainer decision. If maintainers prefer a different name, schema shape, field placement, or a smaller docs-only convention, I can adjust the branch accordingly.

This issue should remain open after the PR is opened, so maintainers can answer the direction questions here.

Proposed Shape

The draft implementation adds optional top-level event metadata:

interface ContextContinuityPacketV1 {
  schema: 'commonly.ccp.v1';
  contextId: string;
  owner: {
    agentName: string;
    instanceId: string;
    podId?: string;
  };
  provenance: {
    source: 'cap.event';
    eventId?: string;
    eventType?: string;
    trigger?: string;
    createdAt?: string;
    deliveredAt?: string;
  };
  freshness?: {
    memoryRevision?: number;
    memoryRevisionAtDelivery?: number;
    lastSeenRevision?: number;
    status: 'valid' | 'stale' | 'unknown';
  };
  refs?: {
    messageId?: string;
    replyToMessageId?: string;
    threadId?: string;
    taskId?: string;
    requestId?: string;
    summaryId?: string;
    integrationId?: string;
    memorySections?: string[];
  };
}

The packet is intended to reference existing kernel state only. It should not copy full prompt content or memory bodies.

Non-Goals

• No new CAP verb.
• No replacement for AgentMemory.
• No new persistence model.
• No default prompt-prefix injection.
• No runtime-specific memory glue.
• No claim that Commonly must adopt Swarm terminology unchanged.

Acceptance Criteria For A Draft PR

• event.continuity is additive and optional.
• Existing CAP payload fields remain unchanged.
• AgentMemory remains the durable continuity primitive.
• CCP references memory freshness but does not store memory bodies.
• Older drivers can ignore the packet safely.
• Docs explain that maintainers can rename or reshape the convention.

References

• OpenAI Swarm comment: RFC: Optional Context Continuity Packet Pattern for Multi-Run Swarm Workflows openai/swarm#87 (comment)
• Commonly CAP: docs/adr/ADR-004-commonly-agent-protocol.md
• Memory as kernel primitive: docs/adr/ADR-003-memory-as-kernel-primitive.md
• Memory propagation: docs/adr/ADR-012-memory-propagation-and-injection.md
• Agent runtime docs: docs/agents/AGENT_RUNTIME.md

[SeCuReDmE-main-dev]

Follow-up PR opened as a full draft implementation: #478

Keeping this issue open for maintainer direction. The PR uses Refs #477 rather than closing the issue, so naming, schema shape, placement, or scope can still be adjusted here.

Original context reference remains: openai/swarm#87 (comment)

[samxu01]

Thanks — you didn't need to open the PR for us to take this seriously, but it helps to have something concrete to point at.

Direction: yes, let's name CCP as a convention. I'd split it in two, though.

The docs, the shared type, and the OpenAPI schema — happy to take those close to as-is. That's the part that's useful to anyone writing a CAP driver, and it costs nothing at runtime.

The computed continuity on the events themselves I'd rather land behind a flag, default off, for now. The reason is just that nothing reads it yet — not the kernel, not the openclaw extension, not our MCP package. We've shipped event metadata ahead of a consumer before (agent reactions) and it sat there as dead surface for weeks. Behind a flag, your implementation is in the tree as the reference and it flips on the day something actually consumes it.

Which is the real question I have: are you planning to read CCP in your own driver (Phi)? If so, that's the consumer, and it changes the math — your branch becomes the thing we turn on by default. Worth knowing who reads it first, because that's what tells us where the packet should actually get built.

A few code-level notes, I'll leave them inline on the PR. Nothing structural — the shape is right.

Keeping this open as the direction thread like you asked.

[SeCuReDmE-main-dev]

for your question : are you planning to read CCP in your own driver (Phi) = no

The short reason is that in my own system I use plithogenic sets and neutrosophic scoring, so the memory/context-continuity mechanism does not behave like a binary-validity system. CCP is very useful for systems that need an explicit continuity packet to carry freshness/provenance across runtime boundaries. In a trinary/neutrosophic system, stale or conflicting memory is handled differently because truth, indeterminacy, and falsity are evaluated internally rather than treated as a simple valid/invalid state.

hope it answer your question i will evaluated your answer and come back too you

[SeCuReDmE-main-dev]

Follow-up commit pushed to PR #478: 0e3612f3.

I updated the branch to match the direction here: CCP remains a Commonly/CAP convention, while computed event attachment is now opt-in and default-off.

Summary of changes:

• computed continuity emission is now opt-in/default-off
  • global: COMMONLY_CCP_ENABLED=1|true|yes|on
  • per install: config.runtime.continuity.enabled === true
• polling, webhook, websocket, and native runtime paths now omit continuity unless enabled
• freshness.status now derives from lastSeenRevision < memoryRevision
• removed the duplicate named backend ContextContinuityPacketV1 interface so the public named contract remains in packages/types/src/events.ts
• matched the sibling-service CJS export pattern
• removed the unvalidated default-on clawdbot-e2e CCP expectation and kept coverage in focused unit tests
• updated docs/OpenAPI wording to state computed event attachment is opt-in/default-off

Validation from backend:

.\node_modules\.bin\jest.cmd --runTestsByPath "__tests__/unit/services/contextContinuityPacketService.test.ts" --runInBand --forceExit --verbose
.\node_modules\.bin\jest.cmd --runTestsByPath "__tests__/unit/services/agentEventService.test.js" --runInBand --forceExit --verbose
npm run tsc:check
npm run build

Results:

• contextContinuityPacketService: PASS, 7 tests
• agentEventService: PASS, 10 tests
• tsc:check: PASS
• build: PASS
• git diff --check: PASS, with Windows LF/CRLF warnings only

[samxu01]

Quick triage: this is already effectively addressed by PR #478, which implements the CCP shape with docs, schema, and opt-in/default-off emission. So I’m marking #477 as stale as a direction issue, not a blocked engineering item.\n\nWhat looks real: the backend implementation path in #478 is concrete and the opt-in guard makes the rollout low-risk.\n\nWhat looks stale / resolved: the issue asks whether Commonly should name CCP and whether the packet should be additive; the PR already answers that with a convention + opt-in implementation.\n\nI’m moving on to a fresh quick-win issue rather than reworking this one.

[SeCuReDmE-main-dev]

ok im looking at your message and all the place you send me i will look at #449 and #478 for more info and will right back give me 5 minute or so so i comprhend all context here

[SeCuReDmE-main-dev]

Thanks, I understand the split now.

I’ll treat #477 as the direction thread and #478 as the code/review surface. I also understand that #449 is a separate quick-win and not a new CCP blocker.

For #478, the follow-up commit 0e3612f keeps computed continuity emission opt-in/default-off and updates the freshness behavior/tests. I’ll wait for maintainer direction on whether anything else should be reduced, renamed, or moved before merge.

[samxu01]

I agree with the direction: treat CCP as a documented convention (types, docs, OpenAPI) but keep the computed continuity emission on CAP events behind a feature flag default off. This provides value to downstream consumers without imposing runtime cost until a consumer exists. Let's merge PR #478 after addressing any minor feedback.

[samxu01]

Completed by openclaw-nova