sdd-agent-platform 0.2.0 → 0.3.0

package/dist/packages/core/src/index.d.ts

@@ -42,6 +42,17 @@ export declare const EVIDENCE_INGESTION_CONTRACT_VERSION = "phase-6.0-evidence-i
 export declare const AGENT_EXECUTION_RECORD_CONTRACT_VERSION = "phase-6.0-agent-execution-record-v1";
 export declare const TEAM_SESSION_RECORD_CONTRACT_VERSION = "phase-6.0-team-session-record-v1";
 export declare const RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION = "phase-6.1-resident-worker-runtime-v1";
+export declare const SDD_EVIDENCE_CONTRACT = "sdd-evidence-v1";
+export declare const SDD_EVIDENCE_VERSION = "1.0.0";
+export declare const ACCEPTANCE_POLICY_RULESET_VERSION = "acceptance-policy-v1";
+export declare const INVOCATION_LEDGER_CONTRACT_VERSION = "phase-6.9-invocation-ledger-v1";
+export declare const ROUTE_CACHE_CONTRACT_VERSION = "phase-6.9-route-cache-v1";
+export declare const RUNTIME_PROFILE_CONTRACT_VERSION = "phase-6.9-runtime-profile-v1";
+export declare const CONTEXT_BUDGET_CONTRACT_VERSION = "phase-6.10-context-budget-v1";
+export declare const COMMAND_OUTPUT_SUMMARY_CONTRACT_VERSION = "sdd-command-output-summary-v1";
+export declare const EVIDENCE_SUMMARY_CONTRACT_VERSION = "sdd-evidence-summary-v1";
+export declare const CONTEXT_PACKAGE_CONTRACT_VERSION = "sdd-context-package-v1";
+export declare const LOG_WORKER_SUMMARY_CONTRACT_VERSION = "sdd-log-worker-summary-v1";
 export type DoctorLevel = 'PASS' | 'WARN' | 'FAIL';
 export type RunStatus = 'created' | 'running' | 'completed' | 'blocked' | 'failed' | 'archived';
 export type LifecycleProfile = 'direct' | 'compact' | 'full' | 'research';
@@ -52,6 +63,12 @@ export type DelegationStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' |
 export type GoalVerifyStatus = 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED';
 export type HarnessVerifyStatus = 'PASS' | 'GAPS' | 'BLOCKED' | 'HUMAN_NEEDED';
 export type ArtifactResultIngestionStatus = 'accepted' | 'rejected';
+export type EvidenceCoverageStatus = 'PASS' | 'FAIL' | 'BLOCKED' | 'REFERENCED_ONLY' | 'MISSING';
+export type EvidenceQualityIssue = 'EMPTY_EVIDENCE' | 'TODO_PLACEHOLDER' | 'TEMPLATE_TEXT' | 'MENTION_ONLY' | 'UNSOURCED_PASS' | 'MISSING_COMMAND_OUTPUT' | 'MISSING_ARTIFACT_REFERENCE' | 'MISSING_MATERIAL_REFERENCE' | 'PROVENANCE_GAP' | 'POLICY_RULE_FAILED' | 'DERIVED_SOURCE_EVIDENCE' | 'PARTITION_SCOPE_VIOLATION';
+export type ContextProfile = 'brief' | 'normal' | 'forensic';
+export type ContextBuildMode = 'do' | 'verify' | 'sync-back' | 'doctor';
+export type ContextSourceKind = 'artifact' | 'run_state' | 'ledger' | 'document' | 'command_output' | 'derived';
+export type ContextSummaryStatus = 'PASS' | 'FAIL' | 'BLOCKED' | 'UNKNOWN';
 export type DetectionConfidence = 'high' | 'medium' | 'low';
 export interface DetectionEvidence {
     kind: string;
@@ -442,6 +459,8 @@ export interface RunState {
     syncBack: {
         mode: 'proposal';
         proposalPath: string | null;
+        proposalDigest?: string | null;
+        sourceVerifyStatus?: GoalVerifyStatus | SingleTaskLoopStatus | null;
         status: 'not_created' | 'proposed' | 'applied';
     };
 }
@@ -868,6 +887,7 @@ export type TeamModeDecisionStatus = 'disabled' | 'enabled' | 'blocked';
 export type TeamModeActivation = 'auto' | 'force' | 'off';
 export type TeamModeSelection = 'off' | 'inspect' | 'review-lite' | 'hyperplan' | 'security-research';
 export type TeamModeCostClass = 'none' | 'low' | 'medium' | 'high';
+export type TeamModeCostRoute = 'not_applicable' | 'downgraded' | 'no_downgrade' | 'blocked';
 export type AgentExecutionRecordStatus = 'claimed' | 'completed' | 'failed' | 'blocked' | 'skipped';
 export type TeamSessionRecordStatus = 'created' | 'completed' | 'blocked' | 'disabled';
 export interface AgentProfileContract {
@@ -1003,6 +1023,9 @@ export interface TeamModePolicy {
     activation: TeamModeActivation;
     costClass: TeamModeCostClass;
     reason: string;
+    costRoute: TeamModeCostRoute;
+    downgradeReason: string | null;
+    trustPolicyEnforced: boolean;
     chiefProfile: AgentProfileId;
     memberProfiles: AgentProfileId[];
     allowedWaves: DelegationWavePolicy[];
@@ -1038,6 +1061,7 @@ export interface AgentExecutionRecord {
     queueItemId: string | null;
     ingestionStatus: ArtifactResultIngestionStatus | null;
     resultStatus: SddResultStatus | null;
+    routeId: string;
     routeDecision: Pick<AgentRouterDecision, 'version' | 'category' | 'recommendedProfile' | 'autonomyCeiling' | 'requiredCapabilities' | 'blockedReason'>;
     evidenceSummary: string;
     createdAt: string;
@@ -1096,6 +1120,22 @@ export interface AgentRouterDecision {
     routingRuleHits?: string[];
     quarantineWarnings?: string[];
     adapterMapping?: AgentRuntimeAdapterMapping | null;
+    cache?: RouteCacheMetadata;
+    profile?: RuntimeProfileSpan[];
+}
+export interface RouteCacheMetadata {
+    contract: typeof ROUTE_CACHE_CONTRACT_VERSION;
+    key: string;
+    status: 'hit' | 'miss' | 'stored';
+    source: 'content_addressed_derived_route';
+    authoritative: false;
+}
+export interface RuntimeProfileSpan {
+    contract: typeof RUNTIME_PROFILE_CONTRACT_VERSION;
+    name: string;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
 }
 export interface AgentSkillTeamRuntimeInspection {
     version: typeof AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION;
@@ -1217,9 +1257,179 @@ export interface SddResultValidationReport {
     valid: boolean;
     result: SddResult | null;
     issues: ContractValidationIssue[];
+    trust?: ArtifactTrustValidationReport;
+}
+export interface EvidenceItem {
+    kind: string;
+    ref: string;
+    summary: string | null;
+}
+export interface EvidenceClaim {
+    contract: typeof SDD_EVIDENCE_CONTRACT;
+    version: typeof SDD_EVIDENCE_VERSION;
+    task: string;
+    acceptance: string;
+    status: EvidenceCoverageStatus;
+    claim: string;
+    sourceArtifact: string;
+    evidence: EvidenceItem[];
+    provenance: string[];
+    policy: string[];
+    rawMetadata: Record<string, string | string[]>;
+}
+export interface EvidenceReasoning {
+    summary: string;
+    ruleIds: string[];
+    issueCodes: EvidenceQualityIssue[];
+}
+export interface PolicyRuleSet {
+    id: typeof ACCEPTANCE_POLICY_RULESET_VERSION;
+    version: string;
+    ruleIds: string[];
+}
+export interface PolicyDecision {
+    status: EvidenceCoverageStatus;
+    ruleSet: PolicyRuleSet;
+    passedRules: string[];
+    failedRules: string[];
+    issueCodes: EvidenceQualityIssue[];
+}
+export interface EvidenceCoverage {
+    acceptanceId: string;
+    status: EvidenceCoverageStatus;
+    claim?: EvidenceClaim;
+    evidence: EvidenceItem[];
+    reasoning?: EvidenceReasoning;
+    policyDecision: PolicyDecision;
+}
+export interface ProvenanceEntity {
+    id: string;
+    kind: 'spec' | 'plan' | 'tasks' | 'artifact' | 'command_output' | 'run_state' | 'material' | string;
+    hash?: string;
+    path?: string;
+}
+export interface ProvenanceActivity {
+    id: string;
+    kind: 'inspect' | 'route' | 'do' | 'verify' | 'artifact_validate' | 'sync_back' | 'policy_evaluate' | 'cache' | string;
+    startedAt?: string;
+    endedAt?: string;
+}
+export interface ProvenanceAgent {
+    id: string;
+    kind: 'runtime' | 'implementer' | 'reviewer' | 'validator' | 'tool' | string;
+}
+export interface ProvenanceLink {
+    relation: 'used' | 'wasGeneratedBy' | 'wasAssociatedWith' | 'wasDerivedFrom' | string;
+    from: string;
+    to: string;
+}
+export interface SddEvidenceAttestation {
+    subject: string;
+    materials: ProvenanceEntity[];
+    invocation: ProvenanceActivity;
+    builder: ProvenanceAgent;
+}
+export interface ArtifactTrustValidationReport {
+    valid: boolean;
+    claims: EvidenceClaim[];
+    issues: ContractValidationIssue[];
+}
+export type InvocationLedgerKind = 'command' | 'tool_invocation' | 'agent' | 'skill' | 'material' | 'policy_evaluation' | 'cache' | 'artifact_hash';
+export interface InvocationLedgerEntry {
+    contract: 'sdd-invocation-ledger-v1';
+    version: typeof INVOCATION_LEDGER_CONTRACT_VERSION;
+    entryId: string;
+    runId: string;
+    taskId: string | null;
+    branch: string | null;
+    kind: InvocationLedgerKind;
+    ref: string;
+    status: string;
+    timestamp: string;
+    artifactPath?: string | null;
+    inputHash?: string | null;
+    outputHash?: string | null;
+    materialRefs: string[];
+    metadata: Record<string, string | number | boolean | null>;
+}
+export interface ContextBudget {
+    contract: typeof CONTEXT_BUDGET_CONTRACT_VERSION;
+    profile: ContextProfile;
+    maxBytes: number;
+    preserve: string[];
+}
+export interface ContextSourceRef {
+    path: string;
+    hash: string;
+    kind: ContextSourceKind;
+}
+export interface CommandOutputSummary {
+    contract: typeof COMMAND_OUTPUT_SUMMARY_CONTRACT_VERSION;
+    authoritative: false;
+    usableForPass: false;
+    source: ContextSourceRef;
+    status: ContextSummaryStatus;
+    highlights: string[];
+    omittedLines: number;
+}
+export interface EvidenceSummaryProjection {
+    contract: typeof EVIDENCE_SUMMARY_CONTRACT_VERSION;
+    authoritative: false;
+    usableForPass: false;
+    runId: string;
+    taskId: string | null;
+    sources: ContextSourceRef[];
+    passCount: number;
+    blockedCount: number;
+    failCount: number;
+    issueCodes: EvidenceQualityIssue[];
+    policyRefs: string[];
+    highlights: string[];
+}
+export interface ContextBuildPackage {
+    contract: typeof CONTEXT_PACKAGE_CONTRACT_VERSION;
+    profile: ContextProfile;
+    mode: ContextBuildMode;
+    agent: string | null;
+    authoritative: false;
+    usableForPass: false;
+    taskId: string;
+    branch: string;
+    mustRead: ContextSourceRef[];
+    optionalRead: ContextSourceRef[];
+    doNotReadUnlessNeeded: ContextSourceRef[];
+    nextCommands: string[];
+    warnings: string[];
+}
+export interface LogWorkerSummary {
+    contract: typeof LOG_WORKER_SUMMARY_CONTRACT_VERSION;
+    authoritative: false;
+    usableForPass: false;
+    runId: string;
+    taskId: string | null;
+    workerId: string;
+    sources: ContextSourceRef[];
+    highlights: string[];
+    forbiddenAuthority: string[];
+}
+export interface EvidenceSummaryOptions {
+    runId: string;
+    taskId?: string;
+}
+export interface ContextBuildOptions {
+    taskId: string;
+    branch?: string;
+    mode: ContextBuildMode;
+    agent?: string;
+    profile?: ContextProfile;
+}
+export interface LogWorkerSummaryValidation {
+    valid: boolean;
+    issues: ContractValidationIssue[];
 }
 export interface SddResultArtifactTemplateOptions {
     branch?: string;
+    runId?: string;
     taskId: string;
     agent: string;
     artifactPath: string;
@@ -1282,8 +1492,10 @@ export interface GoalVerifyOptions {
 }
 export interface AcceptanceCoverageItem {
     acceptance: string;
-    status: GoalVerifyStatus | 'GAP';
+    status: EvidenceCoverageStatus;
     evidence: string;
+    policyDecision?: PolicyDecision;
+    issueCodes?: EvidenceQualityIssue[];
 }
 export interface GoalVerifyResult {
     runId: string;
@@ -1407,6 +1619,7 @@ export interface TaskRunEvidenceContract {
     validation: RunState['validation'];
     gaps: SddTaskGap[];
     syncBackProposal: string | null;
+    invocationLedger: InvocationLedgerEntry[];
     agentExecutions: AgentExecutionRecord[];
     teamSessions: TeamSessionRecord[];
     workerRuntimes: ResidentWorkerRuntimeRecord[];
@@ -1425,6 +1638,7 @@ export interface RunInspection {
     tasks: Record<string, unknown>;
     taskRunEvidence: TaskRunEvidenceContract;
     agentExecutions: AgentExecutionRecord[];
+    invocationLedger: InvocationLedgerEntry[];
     teamSessions: TeamSessionRecord[];
     workerRuntimes: ResidentWorkerRuntimeRecord[];
 }
@@ -1486,6 +1700,8 @@ export interface SyncBackInspection {
     reasons: string[];
     proposalPath: string | null;
     proposal: string | null;
+    proposalDigest: string | null;
+    proposalDigestValid: boolean | null;
     runTaskStatus: string | null;
     markdownTask: SddTask | null;
     markdownStatus: SddTaskStatus | null;
@@ -1509,11 +1725,14 @@ export declare function getSddDir(projectRoot: string): string;
 export declare function getProjectConfigPath(projectRoot: string): string;
 export declare function getRunsDir(projectRoot: string): string;
 export declare function getLocalRunIndexPath(projectRoot: string): string;
+export declare function getRuntimeStorePath(projectRoot: string): string;
 export declare function getRunDir(projectRoot: string, runId: string): string;
 export declare function getArtifactsDir(projectRoot: string, runId: string): string;
 export declare function getAgentExecutionsDir(projectRoot: string, runId: string): string;
 export declare function getTeamSessionsDir(projectRoot: string, runId: string): string;
 export declare function getWorkerRuntimesDir(projectRoot: string, runId: string): string;
+export declare function getInvocationLedgerPath(projectRoot: string, runId: string): string;
+export declare function getRouteCacheDir(projectRoot: string): string;
 export declare function getWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string;
 export declare function getAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string;
 export declare function getTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string;
@@ -1525,6 +1744,8 @@ export declare function writeArtifact(projectRoot: string, runId: string, artifa
     runRelativePath: string;
 }>;
 export declare function readArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string): Promise<string>;
+export declare function appendInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry>;
+export declare function listInvocationLedgerEntries(projectRoot: string, runId: string): Promise<InvocationLedgerEntry[]>;
 export declare function writeAgentExecutionRecord(projectRoot: string, record: AgentExecutionRecord): Promise<AgentExecutionRecord>;
 export declare function writeTeamSessionRecord(projectRoot: string, record: TeamSessionRecord): Promise<TeamSessionRecord>;
 export declare function writeResidentWorkerRuntimeRecord(projectRoot: string, record: ResidentWorkerRuntimeRecord): Promise<ResidentWorkerRuntimeRecord>;
@@ -1573,6 +1794,12 @@ export declare function readLocalRunIndex(projectRoot: string): Promise<LocalRun
 export declare function queryLocalRunIndex(projectRoot: string, query?: LocalRunIndexQuery): Promise<LocalRunIndex>;
 export declare function inspectLocalRunIndex(projectRoot: string): Promise<LocalRunIndexInspection>;
 export declare function inspectRun(projectRoot: string, runId: string): Promise<RunInspection>;
+export declare function parseContextProfile(value: string | null | undefined): ContextProfile;
+export declare function contextBudgetForProfile(profile: ContextProfile): ContextBudget;
+export declare function summarizeCommandOutput(rawOutput: string, source: ContextSourceRef, profile?: ContextProfile): CommandOutputSummary;
+export declare function buildEvidenceSummaryProjection(projectRoot: string, options: EvidenceSummaryOptions): Promise<EvidenceSummaryProjection>;
+export declare function buildContextBuildPackage(projectRoot: string, options: ContextBuildOptions): Promise<ContextBuildPackage>;
+export declare function validateLogWorkerSummary(summary: LogWorkerSummary): LogWorkerSummaryValidation;
 export declare function resolveSddContext(projectRoot: string, options?: {
     branch?: string | null;
     branchSource?: ContextBranchSource;
@@ -1600,6 +1827,7 @@ export declare function applySyncBack(projectRoot: string, options: {
 export declare function doctor(projectRoot: string, options?: {
     allRuns?: boolean;
     latestOnly?: boolean;
+    branch?: string | null;
 }): Promise<DoctorReport>;
 export declare function parseSddBranch(projectRoot: string, branch?: string): Promise<SddTaskModel>;
 export declare function parseSddTasksMarkdown(raw: string, options?: {
@@ -1618,6 +1846,10 @@ export declare function validateSddResult(result: SddResult, options?: {
     expectedAgent?: string;
     runRelativeArtifactPath?: string;
 }): ContractValidationIssue[];
+export declare function parseSddEvidenceMarkdown(raw: string, options?: {
+    expectedTask?: string;
+    sourceArtifact?: string;
+}): ArtifactTrustValidationReport;
 export declare function createDelegationRecord(input: {
     delegationId: string;
     task: string;
@@ -1723,11 +1955,14 @@ export declare function inspectTeamModePolicy(projectRoot: string, options?: {
     enabled?: boolean;
     teamModeActivation?: TeamModeActivation;
 }): Promise<TeamModePolicy>;
-export declare function routeSddTask(projectRoot: string, options: {
+export declare function routeSddTask(projectRoot: string, options?: {
     taskId: string;
     branch?: string;
+    agent?: string;
     teamModeEnabled?: boolean;
     teamModeActivation?: TeamModeActivation;
+    profile?: boolean;
+    cache?: boolean;
 }): Promise<AgentRouterDecision>;
 export declare function inspectQueryStatusContract(projectRoot: string): Promise<QueryStatusContract>;
 export declare function inspectSkillAgentEvalContract(projectRoot: string): Promise<SkillAgentEvalContract>;