brainclaw 0.28.0 → 1.5.3

package/dist/core/schema.js

@@ -33,16 +33,89 @@ function coerceEffortToMinutes(val) {
     }
     return undefined;
 }
+/** Coerce tags from JSON string to array when MCP clients serialize arrays as strings.
+ *  Accepts: string[] (passthrough), '["a","b"]' (JSON parse), 'a,b' (comma split). */
+function coerceTags(val) {
+    if (Array.isArray(val))
+        return val;
+    if (typeof val === 'string') {
+        const trimmed = val.trim();
+        if (trimmed.startsWith('[')) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (Array.isArray(parsed))
+                    return parsed;
+            }
+            catch { /* fall through */ }
+        }
+        if (trimmed.length > 0)
+            return trimmed.split(',').map(t => t.trim()).filter(Boolean);
+        return [];
+    }
+    return val;
+}
+/** Resilient tags schema that accepts string[] or JSON-serialized string. */
+export const TagsSchema = z.preprocess(coerceTags, z.array(z.string()));
+export const TagsWithDefaultSchema = z.preprocess(coerceTags, z.array(z.string()).default([]));
 // --- Entry schemas ---
 export const ConstraintStatusSchema = z.enum(['active', 'resolved', 'expired']);
 export const ConstraintCategorySchema = z.enum(['architecture', 'performance', 'security', 'reliability', 'compatibility', 'process', 'other']);
 export const SeveritySchema = z.enum(['low', 'medium', 'high']);
 export const TrapStatusSchema = z.enum(['active', 'resolved', 'expired']);
-export const PrioritySchema = z.enum(['low', 'medium', 'high']);
+export const PrioritySchema = z.enum(['low', 'medium', 'high', 'critical']);
 export const MemoryVisibilitySchema = z.enum(['shared', 'machine', 'private']);
 export const HandoffStatusSchema = z.enum(['open', 'accepted', 'closed']);
+export const ReviewVerdictSchema = z.enum(['approve', 'request_changes']);
 export const DecisionOutcomeSchema = z.enum(['approved', 'rejected', 'deferred', 'pending']);
 export const MemoryScopeSchema = z.enum(['project', 'machine', 'user']).default('project');
+/**
+ * Typed discriminated-union provenance (Phase 3 slice 3f, P6.3).
+ * Tracks how a record entered the store — drives read filters
+ * (default excludes `legacy` + low-confidence `auto_reflect`), audit
+ * narratives, and federation-safe federation behaviour.
+ */
+export const ProvenanceSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('agent'),
+        agent_id: z.string().optional(),
+        session_id: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal('auto_reflect'),
+        source_session: z.string().optional(),
+        confidence: z.number().min(0).max(1).optional(),
+    }),
+    z.object({
+        kind: z.literal('user'),
+        author: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal('loop_artifact'),
+        loop_id: z.string(),
+        slot: z.string().optional(),
+        turn: z.number().optional(),
+    }),
+    z.object({
+        kind: z.literal('federation'),
+        source_project: z.string(),
+        remote_id: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal('correction'),
+        supersedes: z.string(),
+    }),
+    z.object({
+        kind: z.literal('legacy'),
+    }),
+]);
+/**
+ * Legacy passthrough kept for backwards compatibility with records
+ * that predate slice 3f. Entity shapes carry this (permissive) rather
+ * than `ProvenanceSchema.optional()` so that existing files do not
+ * fail to parse. New writes go through `stampProvenance()` in
+ * entity-operations.ts which enforces the typed shape.
+ */
+export const ProvenancePassthroughSchema = z.unknown().optional();
 export const ConstraintSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     id: z.string(),
@@ -58,9 +131,11 @@ export const ConstraintSchema = z.object({
     status: ConstraintStatusSchema,
     category: ConstraintCategorySchema.optional(),
     scope: MemoryScopeSchema.optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     related_paths: z.array(z.string()).optional(),
+    plan_id: z.string().optional(),
     expires_at: z.string().optional(),
+    provenance: ProvenancePassthroughSchema,
 });
 export const DecisionSchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -78,7 +153,8 @@ export const DecisionSchema = z.object({
     scope: MemoryScopeSchema.optional(),
     related_paths: z.array(z.string()).optional(),
     plan_id: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
+    provenance: ProvenancePassthroughSchema,
 });
 export const TrapSchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -94,13 +170,34 @@ export const TrapSchema = z.object({
     status: TrapStatusSchema.default('active'),
     severity: SeveritySchema,
     scope: MemoryScopeSchema.optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     related_paths: z.array(z.string()).optional(),
     plan_id: z.string().optional(),
     visibility: MemoryVisibilitySchema.default('shared'),
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
     platform_scope: z.string().optional(),
+    provenance: ProvenancePassthroughSchema,
+});
+export const HandoffContractSchema = z.object({
+    files_touched: z.array(z.string()).optional(),
+    pre_conditions: z.array(z.string()).optional(),
+    post_conditions: z.array(z.string()).optional(),
+    tests_to_verify: z.array(z.string()).optional(),
+    linked_plans: z.array(z.string()).optional(),
+});
+export const HandoffReviewSchema = z.object({
+    requester: z.string().optional(),
+    reviewer: z.string().optional(),
+    requested_at: z.string().optional(),
+    thread_id: z.string().optional(),
+    message_id: z.string().optional(),
+    verdict: ReviewVerdictSchema.optional(),
+    reviewed_at: z.string().optional(),
+    reviewed_by: z.string().optional(),
+    summary: z.string().optional(),
+    blocking_issues: z.array(z.string()).optional(),
+    suggestions: z.array(z.string()).optional(),
 });
 export const HandoffSchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -119,11 +216,22 @@ export const HandoffSchema = z.object({
     status: HandoffStatusSchema,
     project: z.string().optional(),
     plan_id: z.string().optional(),
-    tags: z.array(z.string()),
+    narrative: z.string().optional(),
+    tags: TagsSchema,
     related_paths: z.array(z.string()).optional(),
+    contract: HandoffContractSchema.optional(),
+    review: HandoffReviewSchema.optional(),
     snapshot: z.object({
         diff: z.string().optional(),
     }).optional(),
+    provenance: ProvenancePassthroughSchema,
+    /**
+     * Tombstone pointer (P6.1). Present on correction handoffs that
+     * supersede an earlier, incorrect handoff. The original is left
+     * immutable; federation and history still carry both.
+     */
+    superseded_by: z.string().optional(),
+    supersedes: z.string().optional(),
 });
 export const PlanStatusSchema = z.enum(['todo', 'in_progress', 'blocked', 'done', 'dropped']);
 export const PlanStepStatusSchema = z.enum(['todo', 'in_progress', 'testing', 'done', 'blocked']);
@@ -150,7 +258,7 @@ export const PlanItemSchema = z.object({
     priority: PrioritySchema,
     assignee: z.string().optional(),
     project: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     related_paths: z.array(z.string()).optional(),
     depends_on: z.array(z.string()).default([]),
     steps: z.array(PlanStepSchema).optional(),
@@ -159,6 +267,36 @@ export const PlanItemSchema = z.object({
     started_at: z.string().optional(),
     completed_at: z.string().optional(),
 });
+export const SequenceStatusSchema = z.enum(['draft', 'active', 'archived']);
+export const SequenceItemSchema = z.object({
+    planId: z.string(),
+    stepId: z.string().optional(), // Reference a specific step within the plan
+    rank: z.number().int().positive(),
+    hard_after: z.array(z.string()).default([]),
+    soft_after: z.array(z.string()).default([]),
+    lane: z.string().optional(),
+    scope_hint: z.string().optional(),
+    rationale: z.string().optional(),
+});
+export const SequenceSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    short_label: z.string().optional(),
+    name: z.string(),
+    description: z.string().optional(),
+    status: SequenceStatusSchema.default('draft'),
+    items: z.array(SequenceItemSchema).default([]),
+    owner: z.string().optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    author: z.string(),
+    author_id: z.string().optional(),
+    model: z.string().optional(),
+    project_id: z.string().optional(),
+    host_id: z.string().optional(),
+    session_id: z.string().optional(),
+    tags: TagsSchema,
+});
 export const InstructionLayerSchema = z.enum(['global', 'project', 'agent']);
 export const InstructionEntrySchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -170,7 +308,7 @@ export const InstructionEntrySchema = z.object({
     updated_at: z.string(),
     author: z.string(),
     model: z.string().optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     active: z.boolean().default(true),
     supersedes: z.string().optional(),
 });
@@ -183,7 +321,7 @@ export const ProjectCapabilitySchema = z.object({
     category: z.string(), // e.g. "auth", "api", "storage", "testing"
     provided_by: z.string().optional(), // path to implementation
     requires: z.array(z.string()).optional(), // capability IDs this depends on
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     example_usage: z.string().optional(),
     status: CapabilityStatusSchema.default('stable'),
     related_paths: z.array(z.string()).optional(),
@@ -205,7 +343,7 @@ export const ProjectToolSchema = z.object({
     requires: z.array(z.string()).optional(), // tool IDs this depends on
     suggests_for: z.array(z.string()).optional(), // agent types or domains
     invocation_example: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     status: CapabilityStatusSchema.default('stable'),
     related_paths: z.array(z.string()).optional(),
     created_at: z.string(),
@@ -213,6 +351,52 @@ export const ProjectToolSchema = z.object({
     author_id: z.string().optional(),
     model: z.string().optional(),
 });
+// --- Message schema (inter-agent inbox) ---
+export const MessageTypeSchema = z.enum(['assign', 'review', 'rfc', 'info', 'reply']);
+export const MessageStatusSchema = z.enum(['pending', 'read', 'acknowledged', 'archived']);
+export const InboxMessageSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    short_label: z.string().optional(),
+    /** Sender agent name */
+    from: z.string(),
+    /** Target agent name */
+    to: z.string(),
+    /** Message type: assign (work), review (feedback request), rfc (ideation), info (notification), reply (response in thread) */
+    type: MessageTypeSchema,
+    /** Human-readable message body */
+    text: z.string(),
+    /** Reference to a plan, sequence, handoff, or RFC thread */
+    ref: z.string().optional(),
+    /** Structured payload — brief, context, criteria, or any structured data */
+    payload: z.record(z.string(), z.unknown()).optional(),
+    /** File scope relevant to this message */
+    scope: z.string().optional(),
+    /** Whether the recipient must acknowledge */
+    requires_ack: z.boolean().default(false),
+    /** Thread ID for multi-turn conversations (RFC ideation, review rounds) */
+    thread_id: z.string().optional(),
+    /** Status tracking */
+    status: MessageStatusSchema.default('pending'),
+    /** When the message was read */
+    read_at: z.string().optional(),
+    /** When the message was acknowledged */
+    ack_at: z.string().optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    author: z.string(),
+    author_id: z.string().optional(),
+    model: z.string().optional(),
+    project_id: z.string().optional(),
+    host_id: z.string().optional(),
+    session_id: z.string().optional(),
+    /** Top-level claim_id for dispatch routing. Instances filter their inbox by this field.
+     *  Also present in payload.claim_id for backward compat — this top-level field is authoritative. */
+    claim_id: z.string().optional(),
+    /** Top-level assignment_id for Agent SDK protocol. Enables filtering/display without parsing payload. */
+    assignment_id: z.string().optional(),
+    tags: TagsWithDefaultSchema,
+});
 // --- State schema ---
 export const StateSchema = z.object({
     version: z.literal(1),
@@ -228,10 +412,35 @@ export const RedactionConfigSchema = z.object({
     enabled: z.boolean(),
     patterns: z.array(z.string()),
 });
+export const PreinstallThresholdsSchema = z.object({
+    composite_pass: z.number().min(0).max(100).default(70),
+    composite_warn: z.number().min(0).max(100).default(50),
+    supply_chain_block: z.number().min(0).max(100).default(30),
+    vulnerability_block: z.number().min(0).max(100).default(20),
+});
+export const PreinstallWeightsSchema = z.object({
+    supply_chain: z.number().min(0).max(1).default(0.35),
+    vulnerability: z.number().min(0).max(1).default(0.30),
+    quality: z.number().min(0).max(1).default(0.15),
+    maintenance: z.number().min(0).max(1).default(0.15),
+    license: z.number().min(0).max(1).default(0.05),
+});
+export const PreinstallConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    mode: z.enum(['advisory', 'enforced']).default('advisory'),
+    thresholds: PreinstallThresholdsSchema.prefault({}),
+    weights: PreinstallWeightsSchema.prefault({}),
+    cache_ttl_hours: z.number().positive().default(24),
+    fallback_on_error: z.enum(['warn', 'pass', 'block']).default('warn'),
+    allowlist: z.array(z.string()).default([]),
+    denylist: z.array(z.string()).default([]),
+    socket_endpoint: z.string().default('https://mcp.socket.dev/'),
+});
 export const SecurityConfigSchema = z.object({
     mode: z.enum(['warn', 'strict']).default('warn'),
     strict_redaction: z.boolean().default(false),
     block_sensitive_paths: z.boolean().default(true),
+    preinstall: PreinstallConfigSchema.optional(),
 });
 export const MarkdownConfigSchema = z.object({
     max_items_per_section: z.number().default(20),
@@ -241,6 +450,8 @@ export const MarkdownConfigSchema = z.object({
 export const CandidateTypeSchema = z.enum([
     'constraint', 'decision', 'trap', 'handoff',
 ]);
+/** Who originated this candidate. 'auto' = session-end auto-reflect; 'agent' = intentional agent action; 'human' = human-created or unknown legacy item. */
+export const CandidateSourceSchema = z.enum(['auto', 'agent', 'human']);
 export const CandidateStatusSchema = z.enum(['pending', 'accepted', 'rejected']);
 export const CandidateUseSchema = z.object({
     by: z.string(),
@@ -257,7 +468,28 @@ export const CandidateContradictionSchema = z.object({
     score: z.number(),
     kind: z.string(),
 });
-export const CandidateSchema = z.object({
+/** Legacy candidates stored `source` as free-text (e.g. 'session-end:git-diff:sess_xxx',
+ *  'runtime-note:agent:id'). Worker 2 narrowed `source` to an enum. To preserve
+ *  provenance without rewriting files, we migrate free-text values to `origin`
+ *  on read via this preprocess. Files are NOT rewritten — preprocess only
+ *  affects parsed in-memory values. */
+const CANDIDATE_SOURCE_ENUM = new Set(['auto', 'agent', 'human']);
+const candidatePreprocess = (raw) => {
+    if (!raw || typeof raw !== 'object')
+        return raw;
+    const obj = raw;
+    const src = obj.source;
+    if (typeof src === 'string' && !CANDIDATE_SOURCE_ENUM.has(src)) {
+        // Free-text source → preserve into origin (if not already set), drop from source.
+        const clone = { ...obj };
+        if (clone.origin === undefined)
+            clone.origin = src;
+        clone.source = undefined;
+        return clone;
+    }
+    return raw;
+};
+export const CandidateSchema = z.preprocess(candidatePreprocess, z.object({
     schema_version: z.number().int().positive().optional(),
     id: z.string(),
     short_label: z.string().optional(),
@@ -270,8 +502,15 @@ export const CandidateSchema = z.object({
     project_id: z.string().optional(),
     host_id: z.string().optional(),
     session_id: z.string().optional(),
-    source: z.string().optional(),
-    tags: z.array(z.string()),
+    /** Normalized category of the originator. Missing field / unknown legacy value
+     *  falls back to `origin`-based inference, then to 'human'. */
+    source: CandidateSourceSchema.optional().catch(undefined),
+    /** Free-text provenance string preserved for reputation/audit. Examples:
+     *  'session-end:git-diff:sess_xxx', 'runtime-note:<agent>:<note_id>',
+     *  'mcp:quick-capture', 'cross-project:<project>'. Used alongside `source`
+     *  (which is the enum); not narrowed by Zod. */
+    origin: z.string().optional(),
+    tags: TagsSchema,
     status: CandidateStatusSchema,
     // type-specific optional fields
     severity: SeveritySchema.optional(),
@@ -285,13 +524,15 @@ export const CandidateSchema = z.object({
     usage_events: z.array(CandidateUseSchema).default([]),
     last_used_at: z.string().optional(),
     plan_id: z.string().optional(),
+    narrative: z.string().optional(),
     contradictions_detected: z.array(CandidateContradictionSchema).optional(),
     contradiction_summary: z.string().optional(),
     promotion_blocked_reason: z.string().optional(),
     resolved_at: z.string().optional(),
     resolved_by: z.string().optional(),
     resolution_reason: z.string().optional(),
-});
+    provenance: ProvenancePassthroughSchema,
+}));
 export const ReflectiveMemoryConfigSchema = z.object({
     enabled: z.boolean().default(true),
     auto_accept: z.boolean().default(false),
@@ -319,11 +560,14 @@ export const ReputationConfigSchema = z.object({
 });
 // --- Work claims schemas ---
 export const ClaimStatusSchema = z.enum(['active', 'released', 'stale']);
+export const ClaimHandoffModeSchema = z.enum(['self-commit', 'integrator']);
 export const ClaimSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     id: z.string(),
     agent: z.string(),
     agent_id: z.string().optional(),
+    /** OS user who created this claim. */
+    user: z.string().optional(),
     project_id: z.string().optional(),
     host_id: z.string().optional(),
     session_id: z.string().optional(),
@@ -336,6 +580,178 @@ export const ClaimSchema = z.object({
     released_at: z.string().optional(),
     expires_at: z.string().optional(),
     model: z.string().optional(),
+    /** Absolute path to the git worktree associated with this claim, if one was created. */
+    worktree_path: z.string().optional(),
+    /** Handoff mode: "self-commit" = worker commits+merges, "integrator" = another agent reviews+merges. */
+    handoff_mode: ClaimHandoffModeSchema.optional(),
+    /** ISO timestamp when a spawned instance adopted this claim via session_start. */
+    adopted_at: z.string().optional(),
+    /** Message ID of the dispatch assignment that created this claim. For tracing claim→message→instance. */
+    assignment_message_id: z.string().optional(),
+    /** Assignment ID from the Agent SDK runtime protocol. Links claim to its Assignment lifecycle entity. */
+    assignment_id: z.string().optional(),
+});
+// --- Assignment schemas (Agent SDK runtime protocol) ---
+export const AssignmentStatusSchema = z.enum([
+    'created', // Record exists, not yet offered to agent
+    'offered', // Brief delivered to agent inbox
+    'accepted', // Worker acknowledged receipt
+    'started', // Worker reports active work begun
+    'completed', // Worker reports successful completion
+    'failed', // Worker reports failure
+    'blocked', // Worker reports external blocker
+    'timed_out', // Sweeper detected no heartbeat within TTL
+    'expired', // Offered but never accepted within TTL
+    'retrying', // Failed/timed-out assignment being requeued
+    'rerouted', // Blocked assignment rerouted to different agent
+]);
+export const AssignmentArtifactSchema = z.object({
+    type: z.string(),
+    ref: z.string(),
+    description: z.string().optional(),
+});
+export const AssignmentSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    short_label: z.string().optional(),
+    // Cross-references (links, not replacement)
+    claim_id: z.string(),
+    message_id: z.string().optional(),
+    plan_id: z.string().optional(),
+    sequence_id: z.string().optional(),
+    /** For retry chains: original assignment_id. */
+    correlation_id: z.string().optional(),
+    // Actors
+    agent: z.string(),
+    agent_id: z.string().optional(),
+    session_id: z.string().optional(),
+    dispatcher_agent: z.string(),
+    dispatcher_session_id: z.string().optional(),
+    // Task metadata
+    scope: z.string(),
+    description: z.string(),
+    lane: z.string().optional(),
+    worktree_path: z.string().optional(),
+    // Status FSM
+    status: AssignmentStatusSchema,
+    status_reason: z.string().optional(),
+    // Timestamps
+    created_at: z.string(),
+    updated_at: z.string().optional(),
+    offered_at: z.string().optional(),
+    accepted_at: z.string().optional(),
+    started_at: z.string().optional(),
+    completed_at: z.string().optional(),
+    failed_at: z.string().optional(),
+    blocked_at: z.string().optional(),
+    timed_out_at: z.string().optional(),
+    expired_at: z.string().optional(),
+    rerouted_at: z.string().optional(),
+    last_heartbeat_at: z.string().optional(),
+    // Result
+    artifacts: z.array(AssignmentArtifactSchema).default([]),
+    error_message: z.string().optional(),
+    retry_count: z.number().int().default(0),
+    max_retries: z.number().int().default(2),
+    // Timeout config (ms)
+    heartbeat_ttl_ms: z.number().int().default(30 * 60_000), // 30 min
+    acceptance_ttl_ms: z.number().int().default(15 * 60_000), // 15 min
+    tags: TagsWithDefaultSchema,
+});
+// --- AgentRun schemas (execution-layer runtime state) ---
+export const AgentRunTransportSchema = z.enum([
+    'cli_spawn',
+    'manual_command',
+    'inbox_only',
+]);
+export const AgentRunStatusSchema = z.enum([
+    'created',
+    'launching',
+    'waiting_input',
+    'running',
+    'blocked',
+    'completed',
+    'failed',
+    'cancelled',
+    'timed_out',
+    'interrupted',
+]);
+export const AgentRunSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    short_label: z.string().optional(),
+    assignment_id: z.string(),
+    claim_id: z.string(),
+    message_id: z.string().optional(),
+    plan_id: z.string().optional(),
+    sequence_id: z.string().optional(),
+    retry_of_run_id: z.string().optional(),
+    attempt_index: z.number().int().positive().default(1),
+    agent: z.string(),
+    agent_id: z.string().optional(),
+    session_id: z.string().optional(),
+    transport: AgentRunTransportSchema,
+    status: AgentRunStatusSchema,
+    status_reason: z.string().optional(),
+    scope: z.string(),
+    description: z.string(),
+    worktree_path: z.string().optional(),
+    command: z.string().optional(),
+    shell: z.string().optional(),
+    pid: z.number().int().positive().optional(),
+    provider_run_id: z.string().optional(),
+    created_at: z.string(),
+    updated_at: z.string().optional(),
+    launched_at: z.string().optional(),
+    started_at: z.string().optional(),
+    blocked_at: z.string().optional(),
+    completed_at: z.string().optional(),
+    failed_at: z.string().optional(),
+    cancelled_at: z.string().optional(),
+    timed_out_at: z.string().optional(),
+    interrupted_at: z.string().optional(),
+    last_event_at: z.string().optional(),
+    artifacts: z.array(AssignmentArtifactSchema).default([]),
+    error_message: z.string().optional(),
+    tags: TagsWithDefaultSchema,
+});
+// --- ActionRequired schema (runtime pause/resume) ---
+export const ActionRequiredKindSchema = z.enum(['approval', 'user_input', 'clarification', 'plan_approval']);
+export const ActionRequiredStatusSchema = z.enum(['pending', 'resolved', 'rejected', 'cancelled', 'expired']);
+export const ActionRequiredResponseSchema = z.object({
+    outcome: z.enum(['resolved', 'rejected', 'cancelled']),
+    text: z.string().optional(),
+    payload: z.record(z.string(), z.unknown()).optional(),
+    responded_by: z.string(),
+    responded_by_id: z.string().optional(),
+    responded_at: z.string(),
+});
+export const ActionRequiredSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    short_label: z.string().optional(),
+    assignment_id: z.string(),
+    run_id: z.string().optional(),
+    claim_id: z.string().optional(),
+    message_id: z.string().optional(),
+    plan_id: z.string().optional(),
+    sequence_id: z.string().optional(),
+    agent: z.string(),
+    agent_id: z.string().optional(),
+    session_id: z.string().optional(),
+    kind: ActionRequiredKindSchema,
+    status: ActionRequiredStatusSchema.default('pending'),
+    scope: z.string().optional(),
+    title: z.string(),
+    prompt: z.string(),
+    options: z.array(z.string()).default([]),
+    response_schema: z.record(z.string(), z.unknown()).optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    expires_at: z.string().optional(),
+    resolved_at: z.string().optional(),
+    response: ActionRequiredResponseSchema.optional(),
+    tags: TagsWithDefaultSchema,
 });
 // --- Runtime notes schemas ---
 export const RuntimeNoteSchema = z.object({
@@ -349,12 +765,13 @@ export const RuntimeNoteSchema = z.object({
     created_at: z.string(),
     project: z.string().optional(),
     plan_id: z.string().optional(),
-    tags: z.array(z.string()),
+    tags: TagsSchema,
     visibility: MemoryVisibilitySchema.default('shared'),
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
     note_type: z.enum(['observation', 'session_start', 'session_end']).default('observation'),
     model: z.string().optional(),
+    provenance: ProvenancePassthroughSchema,
 });
 // --- AI surface task request schemas ---
 export const AiSurfaceTaskStatusSchema = z.enum(['queued', 'in_progress', 'completed', 'cancelled', 'failed']);
@@ -376,7 +793,7 @@ export const AiSurfaceTaskRequestSchema = z.object({
     status: AiSurfaceTaskStatusSchema.default('queued'),
     requested_outputs: z.array(z.string()).default([]),
     related_paths: z.array(z.string()).optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     claimed_at: z.string().optional(),
     completed_at: z.string().optional(),
     result_note: z.string().optional(),
@@ -391,6 +808,30 @@ export const RuntimeEventTypeSchema = z.enum([
     'task_finished',
     'session_start',
     'session_end',
+    'assignment_created',
+    'assignment_offered',
+    'assignment_accepted',
+    'assignment_started',
+    'assignment_progress',
+    'assignment_completed',
+    'assignment_failed',
+    'assignment_blocked',
+    'assignment_timed_out',
+    'assignment_expired',
+    'assignment_retrying',
+    'assignment_rerouted',
+    'run_created',
+    'run_launching',
+    'run_waiting_input',
+    'run_running',
+    'run_blocked',
+    'run_completed',
+    'run_failed',
+    'run_cancelled',
+    'run_timed_out',
+    'run_interrupted',
+    'plan_cascade_to_done',
+    'candidate_harvested',
 ]);
 export const RuntimeEventSchema = z.object({
     id: z.string(),
@@ -402,14 +843,25 @@ export const RuntimeEventSchema = z.object({
     event_type: RuntimeEventTypeSchema,
     created_at: z.string(),
     text: z.string(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
+    assignment_id: z.string().optional(),
+    run_id: z.string().optional(),
+    claim_id: z.string().optional(),
+    message_id: z.string().optional(),
+    plan_id: z.string().optional(),
+    sequence_id: z.string().optional(),
+    correlation_id: z.string().optional(),
+    scope: z.string().optional(),
+    transport: z.enum(['cli_spawn', 'manual_command', 'inbox_only']).optional(),
+    status: z.string().optional(),
+    status_reason: z.string().optional(),
     // Optional routing and type hints for candidate generation
     candidate_type: CandidateTypeSchema.optional(),
     severity: SeveritySchema.optional(),
     from: z.string().optional(),
     to: z.string().optional(),
     related_paths: z.array(z.string()).optional(),
-    metadata: z.record(z.unknown()).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
     model: z.string().optional(),
 });
 // --- Profile schema ---
@@ -435,6 +887,28 @@ export const ProjectIdentityDocumentSchema = z.object({
     storage_dir: z.string(),
     topology: TopologyModeSchema,
 });
+// --- Agent profile schemas ---
+export const AgentProfileTriggerSchema = z.enum(['manual', 'schedule', 'memory_pressure']);
+export const AgentProfileSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    trust_level: AgentTrustLevelSchema.default('contributor'),
+    trigger: AgentProfileTriggerSchema.default('manual'),
+    scope: z.string().optional(),
+    prompt: z.string().min(1),
+    invoke: z.string().min(1),
+    tags: TagsWithDefaultSchema,
+});
+export const AgentInvokeSchema = z.object({
+    /** CLI command template with {prompt} and {cwd} placeholders */
+    command: z.string(),
+    /** Delivery channel: spawn (launch CLI process) or inbox (deposit message) */
+    channel: z.enum(['spawn', 'inbox']).default('spawn'),
+    /** Max execution time in seconds (default: 600 = 10min) */
+    timeout: z.number().int().positive().default(600),
+    /** Environment variables to set when spawning */
+    env: z.record(z.string(), z.string()).optional(),
+}).strict();
 export const AgentIdentityDocumentSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     version: z.literal(1),
@@ -446,6 +920,9 @@ export const AgentIdentityDocumentSchema = z.object({
     capabilities: z.array(z.string()).default([]),
     identity_key: AgentIdentityKeySchema.optional(),
     model: z.string().optional(),
+    context_profile: z.enum(['dev', 'dense', 'compact', 'copilot', 'quick', 'openclaw', 'ops', 'research']).optional(),
+    /** CLI invoke template for autonomous spawning by coordinator agents */
+    invoke: AgentInvokeSchema.optional(),
 });
 export const ProjectsConfigSchema = z.object({
     strategy: ProjectStrategySchema.default('manual'),
@@ -468,6 +945,15 @@ export const SessionSnapshotSchema = z.object({
     initial_context_hash: z.string().optional(),
     git_sha: z.string().optional(),
 });
+export const SessionActiveProjectSchema = z.object({
+    /** Absolute path to the project directory. */
+    path: z.string(),
+    /** Project name from config.yaml (when available). */
+    name: z.string().optional(),
+    /** ISO timestamp of the switch. */
+    switched_at: z.string(),
+}).strict();
+export const IsolationModeSchema = z.enum(['shared-checkout', 'dedicated-worktree']);
 export const CurrentSessionStateSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     session_id: z.string(),
@@ -476,6 +962,20 @@ export const CurrentSessionStateSchema = z.object({
     agent: z.string(),
     agent_id: z.string(),
     host_id: z.string(),
+    /** OS user who started this session. */
+    user: z.string().optional(),
+    /** Process ID of the agent process (for liveness detection). */
+    pid: z.number().int().positive().optional(),
+    /** LLM model used in this session (e.g. "claude-opus-4-6", "gpt-4.1"). */
+    model: z.string().optional(),
+    /** Session-scoped active project (overrides global active-project.json). */
+    active_project: SessionActiveProjectSchema.optional(),
+    /** Git worktree path for this session (undefined = main worktree / shared checkout). */
+    worktree_path: z.string().optional(),
+    /** Git branch this session is working on. */
+    branch: z.string().optional(),
+    /** Isolation mode: shared-checkout (default) or dedicated-worktree. */
+    isolation_mode: IsolationModeSchema.optional(),
 });
 export const MemorySeedKindSchema = z.enum([
     'command',
@@ -516,7 +1016,7 @@ export const MemorySeedDocumentSchema = z.object({
     source_ref: z.string(),
     confidence: MemorySeedConfidenceSchema,
     related_paths: z.array(z.string()).optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     promotion_hint: z.enum(['constraint', 'decision', 'trap']).optional(),
 });
 export const BootstrapProfileDocumentSchema = z.object({
@@ -547,7 +1047,7 @@ export const BootstrapSuggestionDocumentSchema = z.object({
     source_refs: z.array(z.string()).default([]),
     layer: z.enum(['global', 'project', 'agent']).optional(),
     scope: z.string().optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     related_paths: z.array(z.string()).optional(),
     category: ConstraintCategorySchema.optional(),
     outcome: DecisionOutcomeSchema.optional(),
@@ -581,7 +1081,7 @@ export const BootstrapInterviewAnswerSuggestionSchema = z.object({
     confidence: MemorySeedConfidenceSchema.optional(),
     layer: z.enum(['global', 'project', 'agent']).optional(),
     scope: z.string().optional(),
-    tags: z.array(z.string()).default([]),
+    tags: TagsWithDefaultSchema,
     related_paths: z.array(z.string()).optional(),
     category: ConstraintCategorySchema.optional(),
     outcome: DecisionOutcomeSchema.optional(),
@@ -637,13 +1137,14 @@ export const AgentIntegrationNameSchema = z.enum([
     'antigravity',
     'continue',
     'roo',
+    'kilocode',
     'openclaw',
     'nanoclaw',
     'nemoclaw',
     'picoclaw',
     'zeroclaw',
 ]);
-export const AgentIntegrationSurfaceKindSchema = z.enum(['instructions', 'mcp', 'skill', 'rule', 'hook']);
+export const AgentIntegrationSurfaceKindSchema = z.enum(['instructions', 'mcp', 'skill', 'rule', 'hook', 'permissions']);
 export const AgentIntegrationLocationSchema = z.enum(['workspace', 'machine']);
 export const AgentIntegrationDeclarationSourceSchema = z.enum(['manual', 'detected']);
 export const AgentIntegrationSurfaceSchema = z.object({
@@ -666,6 +1167,7 @@ export const CrossProjectLinkSchema = z.object({
     path: z.string(),
     name: z.string().optional(),
     role: z.enum(['subscriber', 'publisher']).default('subscriber'),
+    channels: z.array(z.string()).optional(),
 });
 export const BrainclawUpdateSourceLocalPackSchema = z.object({
     type: z.literal('local-pack'),
@@ -680,6 +1182,20 @@ export const BrainclawUpdateSourceSchema = z.discriminatedUnion('type', [
     BrainclawUpdateSourceLocalPackSchema,
     BrainclawUpdateSourceNpmSchema,
 ]);
+export const AgentReleaseNotesSchema = z.object({
+    /** One-line summary an agent can surface directly to the operator. */
+    summary: z.string().min(1),
+    /** Concrete impact on agent workflows: new MCP tools, changed behaviour, removed commands. */
+    agent_relevance: z.string().optional(),
+    /** How risky is upgrading without reading the changelog first. */
+    breaking_risk: z.enum(['none', 'low', 'medium', 'high']).default('none'),
+    /** Audience tags ('all', 'multi-agent', 'large-teams'). Absent means 'all'. */
+    recommended_for: z.array(z.string()).optional(),
+    /** Short bullet points the agent can list (max ~5). */
+    highlights: z.array(z.string()).optional(),
+    /** What the agent should tell the operator, e.g. "Safe to auto-install" or "Needs review before upgrading". */
+    action_recommendation: z.string().optional(),
+});
 export const BrainclawLocalReleaseManifestSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     version: z.literal(1),
@@ -690,6 +1206,7 @@ export const BrainclawLocalReleaseManifestSchema = z.object({
     artifact_path: z.string().optional(),
     install_command: z.string().optional(),
     release_notes: z.string().optional(),
+    agent_release_notes: AgentReleaseNotesSchema.optional(),
 });
 export const ConfigSchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -725,5 +1242,13 @@ export const ConfigSchema = z.object({
     cross_project_links: z.array(CrossProjectLinkSchema).optional().default([]),
     implicit_session_ttl: z.string().default('4h'),
     auto_reflect_notes: z.boolean().default(false),
+    auto_refresh_live: z.boolean().default(true),
+    claims: z.object({
+        auto_release_after_hours: z.number().default(24),
+    }).prefault({}),
+    worktree: z.object({
+        shared_paths: z.array(z.string()).default([]),
+        exclude_shared: z.array(z.string()).default([]),
+    }).optional(),
 });
 //# sourceMappingURL=schema.js.map