docs: add core ecosystem spec stubs
This commit is contained in:
parent
5f4134e734
commit
eae3409db5
171
docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md
Normal file
171
docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md
Normal file
@ -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.
|
||||
148
docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md
Normal file
148
docs/ecosystem/ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md
Normal file
@ -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.
|
||||
174
docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md
Normal file
174
docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md
Normal file
@ -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<string, unknown>;
|
||||
};
|
||||
|
||||
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.
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user