From eae3409db5ecc5441691bd7d180875f505cade58 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Fri, 3 Apr 2026 15:41:59 -0700 Subject: [PATCH] docs: add core ecosystem spec stubs --- .../ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md | 171 +++++++++++++++++ .../ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md | 148 +++++++++++++++ .../ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md | 174 ++++++++++++++++++ docs/ecosystem/README.md | 6 +- 4 files changed, 496 insertions(+), 3 deletions(-) create mode 100644 docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md create mode 100644 docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md create mode 100644 docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md diff --git a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md new file mode 100644 index 00000000..a8f74eb2 --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md @@ -0,0 +1,171 @@ +# Ecosystem Agent Runtime Contract + +> **Status:** Draft stub +> **Owner:** `learning_ai_common_plat` +> **Reference inputs:** `claw-code-oss`, `claw-cowork`, `learning_ai_trails`, `learning_ai_flowmonk`, `learning_ai_jarvis_jr` +> **Purpose:** Standardize session state, task state, resume behavior, dispatch semantics, approvals, and audit hooks across agent-capable products. + +--- + +## 1. Problem + +The ecosystem already has multiple agent-runtime ideas: + +- `claw-code` runtime sessions, todos, project memory, resume, MCP lifecycle +- `claw-cowork` task orchestration, dispatch, scheduling, approvals, audit logging +- FlowMonk planning/execution +- JarvisJr coaching/delegation concepts +- ActionTrail review and replay + +Without a shared runtime contract: + +- each repo reinvents session models +- handoff and resume become inconsistent +- audit/replay becomes lossy +- approvals cannot be shared cleanly + +--- + +## 2. Goals + +1. Define the canonical runtime state model. +2. Define session continuity and resume semantics. +3. Define dispatch and handoff metadata. +4. Define approval checkpoints and audit hooks. +5. Allow multiple implementations while preserving one contract. + +## 3. Non-Goals + +1. Forcing all agent products to use one codebase. +2. Standardizing UI/UX across all agent surfaces. +3. Replacing product-specific orchestration logic. + +--- + +## 4. Core Entities + +The shared runtime contract should define: + +- `AgentSession` +- `AgentTask` +- `AgentTodo` +- `AgentRun` +- `AgentApprovalCheckpoint` +- `AgentDispatchRequest` +- `AgentHandoff` +- `AgentActionLog` + +--- + +## 5. Minimum Session Shape + +```ts +type AgentSession = { + sessionId: string; + productId: string; + userId: string; + status: 'active' | 'paused' | 'waiting-approval' | 'completed' | 'failed' | 'cancelled'; + startedAt: string; + updatedAt: string; + resumable: boolean; + currentTaskId?: string | null; + memoryRefs: string[]; + artifactRefs: string[]; + approvalRefs: string[]; + dispatchContext?: AgentDispatchContext | null; +}; + +type AgentTask = { + taskId: string; + sessionId: string; + title: string; + intent: string; + status: 'queued' | 'running' | 'blocked' | 'completed' | 'failed' | 'cancelled'; + priority?: string; + createdAt: string; + updatedAt: string; +}; + +type AgentTodo = { + todoId: string; + sessionId: string; + text: string; + status: 'open' | 'in-progress' | 'done' | 'dropped'; + createdAt: string; + updatedAt: string; +}; +``` + +--- + +## 6. Required Runtime Behaviors + +Every compliant implementation should support: + +1. session creation +2. resumable state checkpoints +3. todo/task updates during execution +4. approval checkpoints +5. action-log emission +6. artifact emission +7. dispatch metadata when execution originates elsewhere +8. replayability in ActionTrail + +--- + +## 7. Dispatch Model + +The contract should support: + +- browser-originated requests +- mobile-originated requests +- desktop-originated requests +- inter-product dispatch +- trusted desktop executor dispatch + +Example: + +```ts +type AgentDispatchContext = { + originSurface: 'browser' | 'mobile' | 'desktop' | 'web' | 'product-api'; + originProductId: string; + dispatchMode: 'interactive' | 'queued' | 'scheduled' | 'remote'; + initiatedAt: string; +}; +``` + +--- + +## 8. First Implementations + +The first conforming runtime integrations should target: + +1. `oss/learning_ai_claw-cowork` +2. `learning_ai_trails` +3. `learning_ai_flowmonk` +4. `learning_ai_jarvis_jr` + +Later: + +5. `learning_voice_ai_agent` transformation workflows +6. shared operator tools in `learning_ai_common_plat` + +--- + +## 9. Key Open Decisions + +1. How much of `claw-code` todo/session semantics should be adopted directly vs normalized? +2. Should scheduled runs create new sessions or new runs under one session? +3. What is the minimum checkpoint payload required for resume-anywhere? +4. Which runtime actions must always emit ActionTrail logs? +5. How should worktree-isolated code tasks be represented vs non-code tasks? + +--- + +## 10. Acceptance Criteria + +1. A dispatched Cowork task can be resumed after interruption without losing audit continuity. +2. A FlowMonk execution can emit task/todo state using the same contract. +3. ActionTrail can replay a run using the shared action-log structure. +4. Approval checkpoints can be handed off to Auth App without losing run context. +5. Product-specific runtimes can remain different internally while still producing the same contract externally. diff --git a/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md b/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md new file mode 100644 index 00000000..0dfe6b06 --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md @@ -0,0 +1,148 @@ +# Ecosystem Approvals And Trust Model + +> **Status:** Draft stub +> **Owner:** `learning_ai_common_plat` +> **Reference inputs:** `learning_ai_smart_auth`, `learning_ai_auth_app`, `learning_ai_trails`, `learning_ai_mac_tooling`, `claw-cowork` +> **Purpose:** Define when the ecosystem should ask for approval, when it should not, and how trust posture affects automation. + +--- + +## 1. Problem + +The ecosystem wants fewer user steps, but it also includes: + +- sensitive auth flows +- high-autonomy agent execution +- browser and desktop capture +- file manipulation +- scheduled automation +- device-risk signals + +Without a shared trust model: + +- users get too many prompts +- approvals are inconsistent +- products duplicate policy logic +- high-risk actions may bypass the wrong controls + +--- + +## 2. Design Principle + +Ask for approval only when risk or ambiguity justifies it. + +That means: + +- trusted identity + trusted device + low-risk action = no redundant prompt +- degraded device trust or destructive action = step-up approval +- every approval should create enough context to avoid repeated re-approval for the same safe run + +--- + +## 3. Approval Inputs + +The trust model should evaluate at least: + +1. actor identity trust +2. device posture +3. action risk level +4. data sensitivity +5. execution mode +6. recent approvals +7. org policy + +Signal sources: + +- SmartAuth identity state +- Auth App approval device +- mac-tooling risk posture +- ActionTrail policy and replay history +- Cowork unattended/destructive-action policy + +--- + +## 4. Suggested Trust Levels + +### Identity trust + +- `anonymous` +- `authenticated` +- `strong-auth` +- `step-up-verified` + +### Device trust + +- `unknown` +- `trusted` +- `degraded` +- `high-risk` + +### Action risk + +- `low` +- `moderate` +- `high` +- `destructive` + +--- + +## 5. Example Policy Matrix + +| Identity | Device | Action | Outcome | +| ------------- | --------- | ---------------- | ------------------------------------ | +| strong-auth | trusted | low | auto-allow | +| strong-auth | trusted | moderate | allow with audit | +| strong-auth | degraded | moderate | require step-up approval | +| authenticated | trusted | high | require approval | +| any | high-risk | high/destructive | block or require explicit escalation | + +--- + +## 6. Shared Approval Record + +```ts +type ApprovalRecord = { + approvalId: string; + userId: string; + productId: string; + sessionId?: string | null; + runId?: string | null; + actionType: string; + actionRisk: 'low' | 'moderate' | 'high' | 'destructive'; + decision: 'approved' | 'denied' | 'expired'; + approvedAt?: string | null; + deviceTrustAtDecision: string; + identityTrustAtDecision: string; + expiresAt?: string | null; +}; +``` + +--- + +## 7. First Use Cases + +1. Cowork destructive file action approval +2. Cowork unattended scheduled run policy +3. JarvisJr delegated action approval +4. FlowMonk high-autonomy execution approval +5. ecosystem auth step-up via Auth App + +--- + +## 8. Key Open Decisions + +1. How long should an approval remain reusable for a session or run? +2. Which actions should always require fresh approval regardless of trust? +3. How should degraded-device posture affect existing sessions in flight? +4. How should org admins override consumer defaults? +5. Which risk signals from mac-tooling are strong enough to block execution outright? + +--- + +## 9. Acceptance Criteria + +1. Low-risk repeated actions do not spam the user with prompts when trust is already high. +2. High-risk or destructive actions consistently require approval across products. +3. Auth App can approve an agent action using one canonical approval payload. +4. ActionTrail can render why an approval was required and what trust state triggered it. +5. Device-risk changes can alter approval behavior without changing product-local policy code. diff --git a/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md b/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md new file mode 100644 index 00000000..3a6ff8a0 --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md @@ -0,0 +1,174 @@ +# Ecosystem Shared Artifact Schema + +> **Status:** Draft stub +> **Owner:** `learning_ai_common_plat` +> **Purpose:** Define the canonical cross-product artifact model so notes, transcripts, plans, memories, trails, routes, and agent outputs can interoperate cleanly. + +--- + +## 1. Problem + +Multiple repos produce durable user-value objects: + +- LysnrAI transcripts +- NoteLett notes +- MindLyst memory entries +- FlowMonk plans +- ChronoMind routines +- ActionTrail audit records +- PeakPulse sessions +- Cowork generated reports and file outputs + +Today these are product-local objects. The ecosystem needs one canonical artifact shape so: + +- artifacts can be linked, searched, and retrieved consistently +- provenance can be preserved +- agent outputs can become user-editable assets +- one user action can create downstream value across products + +--- + +## 2. Goals + +1. Define one envelope schema shared across all products. +2. Preserve product-specific payloads inside a canonical wrapper. +3. Support provenance, lineage, and visibility rules. +4. Support human-created, machine-created, and mixed artifacts. +5. Support cloud-first and local-first storage models. + +## 3. Non-Goals + +1. Replacing product-local domain schemas entirely. +2. Forcing one storage backend for all products. +3. Removing product-specific UX or metadata. + +--- + +## 4. Proposed Canonical Shape + +Every artifact should include: + +- `id` +- `artifactType` +- `productId` +- `sourceSurface` +- `title` +- `summary` +- `createdAt` +- `updatedAt` +- `createdBy` +- `ownership` +- `visibility` +- `status` +- `tags` +- `links` +- `provenance` +- `payload` + +Example types: + +- `transcript` +- `note` +- `memory` +- `plan` +- `routine` +- `habit-checkin` +- `trail-report` +- `route-session` +- `agent-output` +- `document` +- `digest` + +--- + +## 5. Minimum Envelope Fields + +```ts +type ArtifactEnvelope = { + id: string; + artifactType: string; + productId: string; + sourceSurface: string; + title: string | null; + summary: string | null; + createdAt: string; + updatedAt: string; + createdBy: { + actorType: 'user' | 'agent' | 'system' | 'mixed'; + actorId: string | null; + }; + ownership: { + userId: string; + orgId?: string | null; + }; + visibility: { + scope: 'private' | 'org' | 'shared' | 'local-only'; + allowedProducts?: string[]; + }; + status: string; + tags: string[]; + links: ArtifactLink[]; + provenance: ArtifactProvenance; + payload: Record; +}; + +type ArtifactLink = { + relation: + | 'derived-from' + | 'summarizes' + | 'generated-task' + | 'generated-routine' + | 'generated-memory' + | 'evidence-for' + | 'review-of' + | 'attached-to'; + targetArtifactId: string; +}; + +type ArtifactProvenance = { + originProductId: string; + originActionId?: string | null; + sessionId?: string | null; + runId?: string | null; + approvalId?: string | null; + lineage: Array<{ + stepType: string; + productId: string; + actorType: 'user' | 'agent' | 'system'; + timestamp: string; + }>; +}; +``` + +--- + +## 6. First Adopters + +Phase 1 adopters: + +1. `learning_voice_ai_agent` +2. `learning_ai_notes` +3. `learning_multimodal_memory_agents` +4. `learning_ai_flowmonk` +5. `learning_ai_trails` +6. `oss/learning_ai_claw-cowork` + +--- + +## 7. Key Open Decisions + +1. Should artifact IDs be globally unique UUIDs or product-prefixed IDs? +2. Which fields belong in the envelope vs product payload? +3. Should `payload` be versioned per artifact type? +4. How should local-only artifacts from `learning_ai_local_memory_gpt` be represented without leaking sync assumptions? +5. How should binary/file artifacts be referenced: inline metadata vs blob indirection? + +--- + +## 8. Acceptance Criteria + +1. A LysnrAI transcript can be wrapped as an artifact without losing transcript-specific metadata. +2. A NoteLett note can link back to a transcript artifact. +3. A MindLyst memory can record provenance to source transcript/note artifacts. +4. A Cowork output can be stored as an `agent-output` artifact and later opened in NoteLett. +5. ActionTrail can render provenance from the envelope alone. diff --git a/docs/ecosystem/README.md b/docs/ecosystem/README.md index 7a859889..b1677cd0 100644 --- a/docs/ecosystem/README.md +++ b/docs/ecosystem/README.md @@ -13,10 +13,10 @@ Use this folder for: Recommended structure: - [`ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md) — strategy, opportunities, gaps, priorities -- `ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md` — canonical artifact model +- [`ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md) — canonical artifact model - `ECOSYSTEM_EVENT_TAXONOMY.md` — shared events and action-log contract -- `ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md` — shared session, todo, resume, dispatch semantics -- `ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md` — approvals, trust levels, device posture +- [`ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md) — shared session, todo, resume, dispatch semantics +- [`ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md) — approvals, trust levels, device posture - `ECOSYSTEM_MARKETPLACE_UNIFICATION.md` — shared marketplace model - `ECOSYSTEM_PERSONAL_TIMELINE_PRD.md` — unified user activity stream - [`adoption/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/adoption) — per-product adoption notes