codex-workflow-v2 2.0.0-alpha.3 → 2.0.0-alpha.4

package/dist/src/version.js

@@ -1,3 +1,3 @@
 export const PACKAGE_NAME = 'codex-workflow-v2';
-export const PACKAGE_VERSION = '2.0.0-alpha.3';
+export const PACKAGE_VERSION = '2.0.0-alpha.4';
 //# sourceMappingURL=version.js.map

package/dist/src/workflow.d.ts

@@ -1,4 +1,4 @@
-import { type ContextEnvelope, type DiscoveryState, type MilestonePlanInput, type MilestoneState, type KnowledgeSelection, type GraphBinding, type GraphKind, type GraphMode, type GraphRefreshEvidence, type GraphRefreshRequest, type ProjectKnowledgeMap, type ReviewInput, type TaskPlanInput, type TaskState, type WriterLease, type WorkflowRole, type WorkspaceOwner } from './contracts.js';
+import { type ContextEnvelope, type DelegationGrant, type DelegationGrantGate, type DelegationPolicyInput, type DiscoveryState, type MilestonePlanInput, type MilestoneState, type KnowledgeSelection, type GraphBinding, type GraphKind, type GraphMode, type GraphRefreshEvidence, type GraphRefreshRequest, type ProjectKnowledgeMap, type ReviewInput, type TaskPlanInput, type TaskState, type WriterLease, type WorkflowRole, type WorkspaceOwner } from './contracts.js';
 import { type RepositoryIdentity } from './repository.js';
 import { WriterLockManager } from './state/lock.js';
 import { FileStateStore } from './state/store.js';
@@ -29,6 +29,9 @@ export declare class WorkflowService {
     private readonly now;
     constructor(store?: FileStateStore, now?: () => Date);
     context(repository: string): WorkflowContext;
+    prepareDelegation(repository: string, input: DelegationPolicyInput): DelegationGrantGate;
+    grantDelegation(repository: string, input: DelegationPolicyInput, confirmationCode: string): DelegationGrant;
+    revokeDelegation(repository: string, grantId: string, expectedRevision: number, actor: string, reason: string): DelegationGrant;
     startDiscovery(repository: string, input: DiscoveryInput): DiscoveryState;
     updateDiscovery(repository: string, discoveryId: string, expectedRevision: number, patch: DiscoveryPatch): DiscoveryState;
     materializeTask(repository: string, discoveryId: string, expectedRevision: number, title: string, baseBranch?: string, milestoneId?: string | null): {
@@ -42,13 +45,13 @@ export declare class WorkflowService {
         milestoneRoot: string;
     };
     setMilestonePlan(repository: string, milestoneId: string, expectedRevision: number, plan: MilestonePlanInput): MilestoneState;
-    authorizeMilestone(repository: string, milestoneId: string, expectedRevision: number, actor: string, reason?: string): MilestoneState;
+    authorizeMilestone(repository: string, milestoneId: string, expectedRevision: number, actor: string, reason?: string, delegationGrantId?: string | null): MilestoneState;
     validateMilestone(repository: string, milestoneId: string, expectedRevision: number): MilestoneState;
-    acceptMilestone(repository: string, milestoneId: string, expectedRevision: number, actor: string, confirmationCode: string): MilestoneState;
+    acceptMilestone(repository: string, milestoneId: string, expectedRevision: number, actor: string, confirmationCode: string, delegationGrantId?: string | null): MilestoneState;
     cancelMilestone(repository: string, milestoneId: string, expectedRevision: number, reason: string): MilestoneState;
     setTaskPlan(repository: string, taskId: string, expectedRevision: number, plan: TaskPlanInput): TaskState;
     rebindTaskKnowledge(repository: string, taskId: string, expectedRevision: number): TaskState;
-    authorizeTask(repository: string, taskId: string, expectedRevision: number, actor: string, reason?: string): TaskState;
+    authorizeTask(repository: string, taskId: string, expectedRevision: number, actor: string, reason?: string, delegationGrantId?: string | null): TaskState;
     startTask(repository: string, taskId: string, expectedRevision: number, workspaceOwner: WorkspaceOwner): TaskState;
     runStep(repository: string, taskId: string, stepId: string, expectedRevision: number, owner: string, writerToken: string | null): {
         task: TaskState;
@@ -60,7 +63,7 @@ export declare class WorkflowService {
     submitTask(repository: string, taskId: string, expectedRevision: number, writerToken: string): TaskState;
     recordReview(repository: string, taskId: string, expectedRevision: number, review: ReviewInput): TaskState;
     setTaskResult(repository: string, taskId: string, expectedRevision: number, summary: string, limitations: string[]): TaskState;
-    acceptTask(repository: string, taskId: string, expectedRevision: number, actor: string): TaskState;
+    acceptTask(repository: string, taskId: string, expectedRevision: number, actor: string, delegationGrantId?: string | null): TaskState;
     syncTaskBase(repository: string, taskId: string, expectedRevision: number): TaskState;
     mergeTask(repository: string, taskId: string, expectedRevision: number, writerToken: string): TaskState;
     confirmExternalMerge(repository: string, taskId: string, expectedRevision: number, writerToken: string): TaskState;
@@ -69,11 +72,12 @@ export declare class WorkflowService {
         discoveries: DiscoveryState[];
         tasks: TaskState[];
         milestones: MilestoneState[];
+        delegations: DelegationGrant[];
     };
     scanKnowledgeMap(repository: string): ProjectKnowledgeMap;
     showKnowledgeMap(repository: string): ProjectKnowledgeMap;
     knowledgeMapStatus(repository: string): ProjectKnowledgeMap;
-    approveKnowledgeMap(repository: string, expectedRevision: number, selections: KnowledgeSelection[], actor: string): ProjectKnowledgeMap;
+    approveKnowledgeMap(repository: string, expectedRevision: number, selections: KnowledgeSelection[], actor: string, delegationGrantId?: string | null): ProjectKnowledgeMap;
     reconcileKnowledgeMap(repository: string, expectedRevision: number): ProjectKnowledgeMap;
     graphRefreshRequest(repository: string, graphKind: GraphKind, mode?: GraphMode): GraphRefreshRequest;
     graphStatus(repository: string, graphKind: GraphKind, mode?: GraphMode): {
@@ -83,6 +87,10 @@ export declare class WorkflowService {
     bindGraph(repository: string, expectedRevision: number | null, request: GraphRefreshRequest, evidence: GraphRefreshEvidence): GraphBinding;
     recordGraphFallback(repository: string, graphKind: GraphKind, mode: GraphMode, expectedRevision: number | null, reason: string): GraphBinding;
     next(repository: string): Record<string, unknown>;
+    private delegatedAuthorization;
+    private nextForTaskWithDelegation;
+    private delegatedApprovalOptions;
+    private assertDelegationScopeExists;
     private assertExecutionAuthorizationFresh;
     private assertMilestoneAuthorizationFresh;
     private readGraphBindingOrNull;

package/dist/src/workflow.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { PROTOCOL_VERSION, STATE_SCHEMA_VERSION, } from './contracts.js';
 import { renderBrief, renderPlan, renderResult } from './artifacts.js';
+import { assertDelegationCanAuthorize, delegationCanAuthorize, prepareDelegationGrantGate, } from './delegation.js';
 import { assessDiscovery, mergeUnique } from './domain/discovery.js';
 import { pathAllowed, validatePlan } from './domain/validation.js';
 import { WorkflowError } from './errors.js';
@@ -30,6 +31,70 @@ export class WorkflowService {
             locks: new WriterLockManager(this.store.lockRoot(identity.projectId), this.now),
         };
     }
+    prepareDelegation(repository, input) {
+        const { identity } = this.context(repository);
+        const gate = prepareDelegationGrantGate(identity.projectId, input, this.now());
+        this.assertDelegationScopeExists(identity.projectId, gate.policy);
+        return gate;
+    }
+    grantDelegation(repository, input, confirmationCode) {
+        const { identity } = this.context(repository);
+        const gate = prepareDelegationGrantGate(identity.projectId, input, this.now());
+        this.assertDelegationScopeExists(identity.projectId, gate.policy);
+        if (confirmationCode.trim() !== gate.confirmationCode) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Delegation confirmation does not match the exact project and policy.', { projectId: identity.projectId, policyHash: gate.policyHash });
+        }
+        const duplicate = this.store.listDelegations(identity.projectId)
+            .find((grant) => grant.policyHash === gate.policyHash);
+        if (duplicate) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'This exact delegation policy was already issued.', {
+                grantId: duplicate.id,
+                status: duplicate.status,
+            });
+        }
+        const timestamp = this.now().toISOString();
+        return this.store.writeDelegation({
+            schemaVersion: STATE_SCHEMA_VERSION,
+            revision: 0,
+            id: createEntityId('DGR', this.now().getTime()),
+            projectId: identity.projectId,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            kind: 'delegation-grant',
+            status: 'active',
+            principal: gate.policy.principal,
+            delegate: gate.policy.delegate,
+            scope: gate.policy.scope,
+            transitions: gate.policy.transitions,
+            expiresAt: gate.policy.expiresAt,
+            policyHash: gate.policyHash,
+            revokedAt: null,
+            revokedBy: null,
+            revokeReason: null,
+        }, null);
+    }
+    revokeDelegation(repository, grantId, expectedRevision, actor, reason) {
+        const { identity } = this.context(repository);
+        const grant = this.store.readDelegation(identity.projectId, grantId);
+        assertExpectedRevision(grant, expectedRevision);
+        if (grant.status !== 'active') {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grantId} is already ${grant.status}.`);
+        }
+        if (actor.trim() !== grant.principal) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Only the recorded principal may revoke a delegation.', {
+                principal: grant.principal,
+            });
+        }
+        if (!reason.trim())
+            throw new WorkflowError('INVALID_ARGUMENT', 'Delegation revocation requires a reason.');
+        return this.store.writeDelegation({
+            ...grant,
+            status: 'revoked',
+            revokedAt: this.now().toISOString(),
+            revokedBy: grant.principal,
+            revokeReason: reason.trim(),
+        }, expectedRevision);
+    }
     startDiscovery(repository, input) {
         if (!input.goal.trim())
             throw new WorkflowError('INVALID_ARGUMENT', 'Discovery requires a substantive goal.');
@@ -266,7 +331,7 @@ export class WorkflowService {
         this.store.publishArtifact(stagedPlan);
         return saved;
     }
-    authorizeMilestone(repository, milestoneId, expectedRevision, actor, reason = '') {
+    authorizeMilestone(repository, milestoneId, expectedRevision, actor, reason = '', delegationGrantId = null) {
         const { identity } = this.context(repository);
         const milestone = this.store.readMilestone(identity.projectId, milestoneId);
         assertExpectedRevision(milestone, expectedRevision);
@@ -278,6 +343,7 @@ export class WorkflowService {
         if (planHash !== milestone.planHash) {
             throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone Plan changed after it was recorded.');
         }
+        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'milestone.execution_authorize', actor, milestone);
         const event = {
             kind: 'execution',
             decision: 'approved',
@@ -289,6 +355,8 @@ export class WorkflowService {
             evidenceHash: null,
             headCommit: runGit(identity.repositoryRoot, ['rev-parse', milestone.baseBranch]),
             reason,
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
         };
         return this.store.writeMilestone({ ...milestone, status: 'active', planHash, authorizations: [...milestone.authorizations, event] }, expectedRevision);
     }
@@ -355,7 +423,7 @@ export class WorkflowService {
         this.store.publishArtifact(stagedResult);
         return saved;
     }
-    acceptMilestone(repository, milestoneId, expectedRevision, actor, confirmationCode) {
+    acceptMilestone(repository, milestoneId, expectedRevision, actor, confirmationCode, delegationGrantId = null) {
         const { identity } = this.context(repository);
         const milestone = this.store.readMilestone(identity.projectId, milestoneId);
         assertExpectedRevision(milestone, expectedRevision);
@@ -384,6 +452,7 @@ export class WorkflowService {
                 revision: milestone.revision,
             });
         }
+        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'milestone.final_accept', normalizedActor, milestone);
         const event = {
             kind: 'final_acceptance',
             decision: 'approved',
@@ -395,6 +464,8 @@ export class WorkflowService {
             evidenceHash,
             headCommit: currentHead,
             reason: `Confirmed with ${gate.confirmationCode}.`,
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
         };
         return this.store.writeMilestone({
             ...milestone,
@@ -559,7 +630,7 @@ export class WorkflowService {
         this.store.publishArtifact(stagedPlan);
         return saved;
     }
-    authorizeTask(repository, taskId, expectedRevision, actor, reason = '') {
+    authorizeTask(repository, taskId, expectedRevision, actor, reason = '', delegationGrantId = null) {
         const { identity } = this.context(repository);
         const task = this.store.readTask(identity.projectId, taskId);
         assertExpectedRevision(task, expectedRevision);
@@ -570,6 +641,7 @@ export class WorkflowService {
         const root = this.store.taskRoot(identity.projectId, taskId);
         const briefHash = this.store.hashArtifact(root, 'brief.md');
         const planHash = this.store.hashArtifact(root, 'plan.md');
+        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'task.execution_authorize', actor, task);
         const event = {
             kind: 'execution',
             decision: 'approved',
@@ -581,6 +653,8 @@ export class WorkflowService {
             evidenceHash: null,
             headCommit: null,
             reason,
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
         };
         return this.store.writeTask({ ...task, status: 'ready', briefHash, planHash, authorizations: [...task.authorizations, event] }, expectedRevision);
     }
@@ -895,7 +969,7 @@ export class WorkflowService {
         this.store.publishArtifact(stagedResult);
         return saved;
     }
-    acceptTask(repository, taskId, expectedRevision, actor) {
+    acceptTask(repository, taskId, expectedRevision, actor, delegationGrantId = null) {
         const { identity } = this.context(repository);
         const task = this.store.readTask(identity.projectId, taskId);
         assertExpectedRevision(task, expectedRevision);
@@ -910,6 +984,7 @@ export class WorkflowService {
         this.assertReviewFresh(identity.repositoryRoot, task);
         const resultHash = this.store.hashArtifact(root, 'result.md');
         const evidenceHash = this.store.hashArtifact(root, 'evidence.json');
+        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'task.final_accept', actor, task);
         const event = {
             kind: 'final_acceptance',
             decision: 'approved',
@@ -921,6 +996,8 @@ export class WorkflowService {
             evidenceHash,
             headCommit: headCommit(identity.repositoryRoot),
             reason: '',
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
         };
         return this.store.writeTask({
             ...task,
@@ -1024,6 +1101,7 @@ export class WorkflowService {
             discoveries: this.store.listDiscoveries(identity.projectId),
             tasks: this.store.listTasks(identity.projectId),
             milestones: this.store.listMilestones(identity.projectId),
+            delegations: this.store.listDelegations(identity.projectId),
         };
     }
     scanKnowledgeMap(repository) {
@@ -1049,12 +1127,21 @@ export class WorkflowService {
         const scanned = scanProjectKnowledge(identity.repositoryRoot, identity.projectId, this.now());
         return inspectKnowledgeMap(current, scanned);
     }
-    approveKnowledgeMap(repository, expectedRevision, selections, actor) {
+    approveKnowledgeMap(repository, expectedRevision, selections, actor, delegationGrantId = null) {
         const { identity } = this.context(repository);
         const current = this.store.readKnowledgeMap(identity.projectId);
         assertExpectedRevision(current, expectedRevision);
         const inspected = inspectKnowledgeMap(current, scanProjectKnowledge(identity.repositoryRoot, identity.projectId, this.now()));
+        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'project_memory.approve', actor, inspected);
         const approved = applyKnowledgeSelections(inspected, selections, actor, this.now());
+        if (!approved.approval) {
+            throw new WorkflowError('STATE_CORRUPT', 'Knowledge Map approval was not recorded.');
+        }
+        approved.approval = {
+            ...approved.approval,
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
+        };
         return this.store.writeKnowledgeMap(approved, expectedRevision);
     }
     reconcileKnowledgeMap(repository, expectedRevision) {
@@ -1095,16 +1182,21 @@ export class WorkflowService {
         const activeTask = status.tasks.find((task) => taskIsActionableFromRepositoryNext(task, milestonesById));
         if (activeTask) {
             if (!taskCanRebindKnowledge(activeTask) && activeTask.status !== 'planning') {
-                return nextForTask(activeTask);
+                return this.nextForTaskWithDelegation(status.projectId, activeTask);
             }
             const knowledgeMap = this.knowledgeMapStatus(repository);
             if (knowledgeMap.status !== 'active' || !knowledgeMap.approval) {
+                const action = knowledgeMap.status === 'stale' ? 'project-memory reconcile' : 'project-memory approve';
+                const delegatedApprovalOptions = action === 'project-memory approve'
+                    ? this.delegatedApprovalOptions(status.projectId, 'project_memory.approve', knowledgeMap)
+                    : [];
                 return {
                     scope: 'project-memory',
                     status: knowledgeMap.status,
-                    action: knowledgeMap.status === 'stale' ? 'project-memory reconcile' : 'project-memory approve',
+                    action,
                     revision: knowledgeMap.revision,
                     taskId: activeTask.id,
+                    ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
                 };
             }
             const knowledgeMapHash = hashKnowledgeMap(knowledgeMap);
@@ -1122,7 +1214,7 @@ export class WorkflowService {
                     knowledgeMapHash,
                 };
             }
-            return nextForTask(activeTask);
+            return this.nextForTaskWithDelegation(status.projectId, activeTask);
         }
         const activeMilestone = status.milestones.find((milestone) => !['accepted', 'cancelled'].includes(milestone.status));
         if (activeMilestone) {
@@ -1149,21 +1241,29 @@ export class WorkflowService {
                         reason: 'final validation evidence is stale',
                     };
                 }
+                const delegatedApprovalOptions = this.delegatedApprovalOptions(status.projectId, 'milestone.final_accept', activeMilestone);
                 return {
                     scope: 'milestone',
                     id: activeMilestone.id,
                     status: activeMilestone.status,
-                    action: 'await explicit human final acceptance',
+                    action: delegatedApprovalOptions.length > 0
+                        ? 'milestone accept using delegated approval or await explicit human final acceptance'
+                        : 'await explicit human final acceptance',
                     revision: activeMilestone.revision,
                     requiredHumanGate: milestoneFinalAcceptanceGate(activeMilestone, evidence.headCommit),
+                    ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
                 };
             }
+            const delegatedApprovalOptions = activeMilestone.status === 'awaiting_execution_authorization'
+                ? this.delegatedApprovalOptions(status.projectId, 'milestone.execution_authorize', activeMilestone)
+                : [];
             return {
                 scope: 'milestone',
                 id: activeMilestone.id,
                 status: activeMilestone.status,
                 action: nextForMilestone(activeMilestone),
                 revision: activeMilestone.revision,
+                ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
             };
         }
         const activeDiscovery = status.discoveries.find((discovery) => !['materialized', 'abandoned'].includes(discovery.status));
@@ -1178,6 +1278,51 @@ export class WorkflowService {
         }
         return { scope: 'repository', status: 'idle', action: 'discovery start' };
     }
+    delegatedAuthorization(projectId, grantId, transition, actor, target) {
+        if (!grantId) {
+            if (actor.trim().startsWith('agent:')) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'An agent actor requires an explicit delegated approval grant.');
+            }
+            return null;
+        }
+        const grant = this.store.readDelegation(projectId, grantId);
+        return assertDelegationCanAuthorize(grant, transition, actor, target, this.now());
+    }
+    nextForTaskWithDelegation(projectId, task) {
+        const transition = task.status === 'awaiting_execution_authorization'
+            ? 'task.execution_authorize'
+            : task.status === 'awaiting_final_acceptance'
+                ? 'task.final_accept'
+                : null;
+        const delegatedApprovalOptions = transition
+            ? this.delegatedApprovalOptions(projectId, transition, task)
+            : [];
+        return {
+            ...nextForTask(task),
+            ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
+        };
+    }
+    delegatedApprovalOptions(projectId, transition, target) {
+        return this.store.listDelegations(projectId)
+            .filter((grant) => delegationCanAuthorize(grant, transition, target, this.now()))
+            .map((grant) => ({
+            grantId: grant.id,
+            principal: grant.principal,
+            delegate: grant.delegate,
+            transition,
+            scope: grant.scope,
+            expiresAt: grant.expiresAt,
+            policyHash: grant.policyHash,
+        }));
+    }
+    assertDelegationScopeExists(projectId, policy) {
+        if (policy.scope.kind === 'task') {
+            this.store.readTask(projectId, policy.scope.id);
+            return;
+        }
+        if (policy.scope.kind === 'milestone')
+            this.store.readMilestone(projectId, policy.scope.id);
+    }
     assertExecutionAuthorizationFresh(task) {
         const root = this.store.taskRoot(task.projectId, task.id);
         const authorization = [...task.authorizations]