@zhin.js/agent 1.1.13 → 1.1.14

package/lib/workroom/human-ingress-orchestrator.js

@@ -0,0 +1,234 @@
+import { deepFreezeWorkroomValue as deepFreeze, digestCanonicalWorkroomValue, } from './canonical-value.js';
+import { assertWorkflowPlanProposal } from './workflow-plan-builder.js';
+import { WorkroomPlanGateUnauthorizedError, } from './plan-approval-control.js';
+/** Typed fail-closed planning outcome persisted by HumanIngressApplication. */
+export class WorkroomPlanningClarificationError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Workroom planning requires clarification: ${reason}`);
+        this.reason = reason;
+        this.name = 'WorkroomPlanningClarificationError';
+    }
+}
+/**
+ * Production proposal boundary: resolve immutable source + current Catalog
+ * authority, then route to a typed proposal/authority port. It never exposes a
+ * generic Kernel command to a model.
+ */
+export class ProductionHumanIngressOrchestratorPort {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async apply(request) {
+        if (request.operationId !== request.identity.operationId
+            || request.proposal.projectId !== request.identity.projectId
+            || request.proposal.digest !== request.identity.proposalDigest
+            || request.proposal.intent !== request.kind) {
+            throw new Error('Human ingress Orchestrator request identity is inconsistent');
+        }
+        const authority = await this.options.resolveProject(request.identity.projectId);
+        if (!authority)
+            throw new Error('Human ingress Project is absent from the active Workroom Catalog');
+        const proposedAgent = request.proposal.kind === 'project_inbox'
+            ? request.proposal.target.agentDefinitionId
+            : undefined;
+        if (request.proposal.kind === 'project_inbox'
+            && (!proposedAgent || proposedAgent !== authority.orchestratorAgentDefinitionId)) {
+            throw new Error('Human ingress Orchestrator binding does not match the active Workroom Catalog');
+        }
+        const source = await this.options.sources.read(request.proposal.sourceEvent);
+        if (source.conversationKey !== request.proposal.sourceEvent.conversationKey
+            || source.event.type !== 'message.created'
+            || source.event.message.actor?.id !== request.proposal.principal.subjectId) {
+            throw new Error('Human ingress source does not match the proposed Project principal scope');
+        }
+        if (!await this.options.authorizeProjectSource(deepFreeze({
+            projectId: request.identity.projectId,
+            proposal: request.proposal,
+            source,
+        }))) {
+            throw new Error('Human ingress source is not authorized by the exact Project binding');
+        }
+        const common = deepFreeze({
+            version: 1,
+            operationId: request.operationId,
+            projectId: request.identity.projectId,
+            projectRevision: authority.projectRevision,
+            projectDigest: authority.projectDigest,
+            orchestratorAgentDefinitionId: authority.orchestratorAgentDefinitionId,
+            orchestratorAuthorityDigest: authority.orchestratorAuthorityDigest,
+            principalId: request.proposal.principal.principalId,
+            source,
+            ...(request.proposal.projectionReply
+                ? { projectionReply: request.proposal.projectionReply }
+                : {}),
+        });
+        if (request.kind === 'discussion') {
+            const receipt = await (this.options.discussions ?? createContentFreeDiscussionProposalPort()).propose(deepFreeze({
+                ...common,
+                authority: 'non_authoritative',
+                text: source.text,
+            }));
+            validateReceipt(receipt);
+            return applied(request, 'discussion_recorded', receipt);
+        }
+        if (request.kind === 'control') {
+            if (!this.options.controls)
+                return clarification(request, 'unauthorized_control');
+            if (request.proposal.authorityRequirement === 'none') {
+                throw new Error('Human ingress control lacks a typed authority requirement');
+            }
+            const decision = await this.options.controls.apply(deepFreeze({
+                ...common,
+                authorityRequirement: request.proposal.authorityRequirement,
+                text: source.text,
+            }));
+            if (decision.status === 'clarification_required') {
+                return clarification(request, decision.reason, decision.candidateRefs);
+            }
+            validateReceipt(decision);
+            return applied(request, 'control_proposal_submitted', decision);
+        }
+        if (!/^\/(?:work|task)(?:\s|$)/iu.test(source.text)) {
+            return clarification(request, 'missing_work_scope');
+        }
+        const title = source.text.replace(/^\/(?:work|task)(?:\s+|$)/iu, '').trim();
+        if (!title)
+            return clarification(request, 'missing_work_scope');
+        if (!this.options.planning)
+            return clarification(request, 'planning_unavailable');
+        let plan;
+        try {
+            plan = await this.options.planning.propose(common);
+        }
+        catch (error) {
+            if (error instanceof WorkroomPlanningClarificationError) {
+                return clarification(request, error.reason);
+            }
+            throw error;
+        }
+        assertWorkflowPlanProposal(plan);
+        if (plan.projectId !== request.identity.projectId
+            || plan.proposalId !== request.operationId
+            || plan.parameterDigest !== source.digest
+            || plan.authority.projectRevision !== authority.projectRevision
+            || plan.authority.projectDigest !== authority.projectDigest
+            || plan.authority.orchestratorAgentDefinitionId !== authority.orchestratorAgentDefinitionId
+            || plan.authority.orchestratorAuthorityDigest !== authority.orchestratorAuthorityDigest) {
+            throw new Error('Human ingress planner returned a Plan outside the exact operation/source scope');
+        }
+        const receipt = await this.options.kernel.admitWorkflowPlan({
+            operationId: request.operationId,
+            projectId: request.identity.projectId,
+            title,
+            sourceEventRef: source.ref,
+            sourceEventDigest: source.digest,
+            orchestratorAgentDefinitionId: authority.orchestratorAgentDefinitionId,
+            plan,
+        });
+        await this.options.afterPlanAdmission?.({
+            operationId: request.operationId,
+            projectId: request.identity.projectId,
+            plan,
+            receipt,
+        });
+        return applied(request, 'plan_proposal_submitted', receipt);
+    }
+}
+/** Content-free receipt; durable application journal owns exact replay state. */
+export function createContentFreeDiscussionProposalPort() {
+    return Object.freeze({
+        propose(input) {
+            const receiptRef = `workroom-discussion:${encodeURIComponent(input.operationId)}`;
+            return Object.freeze({
+                receiptRef,
+                receiptDigest: digestCanonicalWorkroomValue({
+                    version: 1,
+                    kind: 'non_authoritative_discussion_proposal',
+                    operationId: input.operationId,
+                    projectId: input.projectId,
+                    sourceDigest: input.source.digest,
+                }),
+            });
+        },
+    });
+}
+/** Strict human control grammar; all mutable scope is re-read from Kernel facts. */
+export function createPlanGateHumanIngressControlPort(kernel) {
+    return Object.freeze({
+        async apply(input) {
+            const match = /^\/control\s+plan-gate\s+(approve|reject|request-changes|cancel)\s+(\S+)\s+(\S+)\s+(\S+)(?:\s+(.+))?$/iu
+                .exec(input.text.trim());
+            if (!match) {
+                return Object.freeze({
+                    status: 'clarification_required',
+                    reason: 'missing_control_target',
+                    candidateRefs: Object.freeze([]),
+                });
+            }
+            const [, rawDecision, runId, taskKey, gateId, reason] = match;
+            const state = await kernel.read(input.projectId, runId);
+            const task = state.tasks[taskKey];
+            if (!task || !task.blockers.some(blocker => blocker.id === gateId && blocker.kind === 'approval')) {
+                return Object.freeze({
+                    status: 'clarification_required',
+                    reason: 'stale_target',
+                    candidateRefs: Object.freeze([]),
+                });
+            }
+            const decision = rawDecision === 'request-changes'
+                ? 'request_changes'
+                : rawDecision;
+            let receipt;
+            try {
+                receipt = await kernel.decidePlanApprovalGate({
+                    operationId: input.operationId,
+                    projectId: input.projectId,
+                    runId: runId,
+                    taskKey: taskKey,
+                    taskRevision: task.revision,
+                    gateId: gateId,
+                    expectedSequence: state.sequence,
+                    decision,
+                    reason: reason?.trim() || `Sponsor Plan Gate ${decision}`,
+                    sponsorPrincipalId: input.principalId,
+                    sponsorAuthorityRef: `human-ingress:${input.source.digest}`,
+                });
+            }
+            catch (error) {
+                if (error instanceof WorkroomPlanGateUnauthorizedError) {
+                    return Object.freeze({
+                        status: 'clarification_required',
+                        reason: 'unauthorized_control',
+                        candidateRefs: Object.freeze([]),
+                    });
+                }
+                throw error;
+            }
+            return Object.freeze({
+                status: 'authorized',
+                receiptRef: receipt.receiptRef,
+                receiptDigest: receipt.receiptDigest,
+            });
+        },
+    });
+}
+function applied(request, kind, receipt) {
+    return deepFreeze({ ...request.identity, status: 'applied', kind, ...receipt });
+}
+function clarification(request, reason, candidateRefs = []) {
+    return deepFreeze({
+        ...request.identity,
+        status: 'clarification_required',
+        reason,
+        candidateRefs: [...new Set(candidateRefs)].sort(),
+    });
+}
+function validateReceipt(value) {
+    if (!value || typeof value.receiptRef !== 'string' || !value.receiptRef.trim()
+        || !/^sha256:[a-f0-9]{64}$/u.test(value.receiptDigest)) {
+        throw new Error('Human ingress typed proposal receipt is invalid');
+    }
+}
+//# sourceMappingURL=human-ingress-orchestrator.js.map

package/lib/workroom/human-ingress-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-ingress-orchestrator.js","sourceRoot":"","sources":["../../src/workroom/human-ingress-orchestrator.ts"],"names":[],"mappings":"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"}

package/lib/workroom/human-ingress-source-reader.d.ts

@@ -0,0 +1,29 @@
+import { type ConversationEvent, type ConversationEventStore } from '@zhin.js/im-contract';
+import type { HumanIngressSourceAnchor } from './human-ingress.js';
+export interface CanonicalHumanIngressSource {
+    readonly version: 1;
+    readonly ref: string;
+    readonly digest: string;
+    readonly sequence: number;
+    readonly conversationKey: string;
+    readonly eventId: string;
+    readonly text: string;
+    readonly event: ConversationEvent;
+}
+export interface HumanIngressSourceReaderPort {
+    read(source: HumanIngressSourceAnchor): Promise<CanonicalHumanIngressSource>;
+}
+/** Digest binds the database sequence and complete canonical event payload. */
+export declare function digestHumanIngressConversationEvent(sequence: number, event: ConversationEvent): string;
+export declare function humanIngressConversationEventRef(event: ConversationEvent): string;
+/**
+ * Reads only the canonical ConversationEventStore. The caller-provided anchor
+ * is evidence, never content: sequence, ref, conversation and full-event digest
+ * all have to name the same durable message.created event.
+ */
+export declare class ConversationEventHumanIngressSourceReader implements HumanIngressSourceReaderPort {
+    readonly store: ConversationEventStore | (() => ConversationEventStore);
+    constructor(store: ConversationEventStore | (() => ConversationEventStore));
+    read(source: HumanIngressSourceAnchor): Promise<CanonicalHumanIngressSource>;
+}
+//# sourceMappingURL=human-ingress-source-reader.d.ts.map

package/lib/workroom/human-ingress-source-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-ingress-source-reader.d.ts","sourceRoot":"","sources":["../../src/workroom/human-ingress-source-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,sBAAsB,CAAC;AAK9B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAEnE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;CAC9E;AAED,+EAA+E;AAC/E,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAKR;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAGjF;AAED;;;;GAIG;AACH,qBAAa,yCACb,YAAW,4BAA4B;IACzB,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,CAAC,MAAM,sBAAsB,CAAC;gBAA9D,KAAK,EAAE,sBAAsB,GAAG,CAAC,MAAM,sBAAsB,CAAC;IAE7E,IAAI,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,2BAA2B,CAAC;CAqCnF"}

package/lib/workroom/human-ingress-source-reader.js

@@ -0,0 +1,119 @@
+import { conversationRefKey, messageRefKey, } from '@zhin.js/im-contract';
+import { deepFreezeWorkroomValue as deepFreeze, digestCanonicalWorkroomValue, } from './canonical-value.js';
+/** Digest binds the database sequence and complete canonical event payload. */
+export function digestHumanIngressConversationEvent(sequence, event) {
+    if (!Number.isSafeInteger(sequence) || sequence < 1) {
+        throw new Error('Human ingress source sequence must be a positive safe integer');
+    }
+    return digestCanonicalWorkroomValue({ version: 1, sequence, event });
+}
+export function humanIngressConversationEventRef(event) {
+    requireText(event.eventId, 'eventId');
+    return `conversation-event:${event.eventId}`;
+}
+/**
+ * Reads only the canonical ConversationEventStore. The caller-provided anchor
+ * is evidence, never content: sequence, ref, conversation and full-event digest
+ * all have to name the same durable message.created event.
+ */
+export class ConversationEventHumanIngressSourceReader {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async read(source) {
+        const anchor = normalizeAnchor(source);
+        const eventId = anchor.ref.slice('conversation-event:'.length);
+        const store = typeof this.store === 'function' ? this.store() : this.store;
+        const events = await store.listBetween(parseConversationKey(anchor.conversationKey), anchor.sequence - 1, anchor.sequence, 1);
+        const selected = events[0];
+        if (!selected || selected.sequence !== anchor.sequence) {
+            throw new Error('Canonical human ingress source event was not found at the anchored sequence');
+        }
+        const event = selected.event;
+        if (event.type !== 'message.created') {
+            throw new Error('Canonical human ingress source must be message.created');
+        }
+        if (event.eventId !== eventId
+            || humanIngressConversationEventRef(event) !== anchor.ref
+            || conversationRefKey(event.conversation) !== anchor.conversationKey
+            || conversationRefKey(event.message.ref.conversation) !== anchor.conversationKey
+            || event.eventId !== `message:${messageRefKey(event.message.ref)}`) {
+            throw new Error('Canonical human ingress source ref or conversation does not match the durable event');
+        }
+        const digest = digestHumanIngressConversationEvent(selected.sequence, event);
+        if (digest !== anchor.digest) {
+            throw new Error('Canonical human ingress source digest does not match the durable event');
+        }
+        return deepFreeze({
+            version: 1,
+            ...anchor,
+            eventId,
+            text: plainText(event),
+            event,
+        });
+    }
+}
+/*
+ * listBetween requires a structured ConversationRef. The anchor intentionally
+ * stores only the canonical key, so use getMessage to recover that structure
+ * is impossible without parsing. Conversation keys are canonical JSON in the
+ * IM contract; keep parsing private and verify round-trip before use.
+ */
+function parseConversationKey(key) {
+    const [adapter, endpointId, kind, id, parentKind, parentId, threadId, ...extra] = key.split('\0');
+    if (extra.length > 0 || !adapter || !endpointId || !id
+        || (kind !== 'private' && kind !== 'group' && kind !== 'channel')
+        || (Boolean(parentKind) !== Boolean(parentId))
+        || (parentKind && parentKind !== 'private' && parentKind !== 'group' && parentKind !== 'channel')) {
+        throw new Error('Human ingress source conversation key is not canonical');
+    }
+    const parsed = Object.freeze({
+        endpoint: Object.freeze({ adapter, id: endpointId }),
+        kind,
+        id,
+        ...(parentKind && parentId
+            ? { parent: Object.freeze({
+                    kind: parentKind,
+                    id: parentId,
+                }) }
+            : {}),
+        ...(threadId ? { threadId } : {}),
+    });
+    if (conversationRefKey(parsed) !== key) {
+        throw new Error('Human ingress source conversation key is not canonical');
+    }
+    return parsed;
+}
+function normalizeAnchor(source) {
+    const snapshot = structuredClone(source);
+    if (!snapshot || typeof snapshot !== 'object'
+        || Object.keys(snapshot).sort().join(',') !== 'conversationKey,digest,ref,sequence') {
+        throw new Error('Human ingress source anchor shape is invalid');
+    }
+    requireText(snapshot.ref, 'ref');
+    if (!snapshot.ref.startsWith('conversation-event:')) {
+        throw new Error('Human ingress source ref must identify a conversation event');
+    }
+    if (!/^sha256:[a-f0-9]{64}$/u.test(snapshot.digest)) {
+        throw new Error('Human ingress source digest must be canonical SHA-256');
+    }
+    if (!Number.isSafeInteger(snapshot.sequence) || snapshot.sequence < 1) {
+        throw new Error('Human ingress source sequence must be a positive safe integer');
+    }
+    requireText(snapshot.conversationKey, 'conversationKey');
+    return deepFreeze(snapshot);
+}
+function plainText(event) {
+    return event.message.segments
+        .filter(segment => segment.type === 'text')
+        .map(segment => String(segment.data.text ?? ''))
+        .join('')
+        .trim();
+}
+function requireText(value, label) {
+    if (typeof value !== 'string' || !value.trim() || value !== value.trim()) {
+        throw new Error(`Human ingress source ${label} must be canonical text`);
+    }
+}
+//# sourceMappingURL=human-ingress-source-reader.js.map

package/lib/workroom/human-ingress-source-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-ingress-source-reader.js","sourceRoot":"","sources":["../../src/workroom/human-ingress-source-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,aAAa,GAGd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,uBAAuB,IAAI,UAAU,EACrC,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAkB9B,+EAA+E;AAC/E,MAAM,UAAU,mCAAmC,CACjD,QAAgB,EAChB,KAAwB;IAExB,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,4BAA4B,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,gCAAgC,CAAC,KAAwB;IACvE,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACtC,OAAO,sBAAsB,KAAK,CAAC,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,yCAAyC;IAE/B;IAArB,YAAqB,KAA8D;QAA9D,UAAK,GAAL,KAAK,CAAyD;IAAG,CAAC;IAEvF,KAAK,CAAC,IAAI,CAAC,MAAgC;QACzC,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC/D,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;QAC3E,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,WAAW,CACpC,oBAAoB,CAAC,MAAM,CAAC,eAAe,CAAC,EAC5C,MAAM,CAAC,QAAQ,GAAG,CAAC,EACnB,MAAM,CAAC,QAAQ,EACf,CAAC,CACF,CAAC;QACF,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;QACjG,CAAC;QACD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO;eACxB,gCAAgC,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,GAAG;eACtD,kBAAkB,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,MAAM,CAAC,eAAe;eACjE,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,MAAM,CAAC,eAAe;eAC7E,KAAK,CAAC,OAAO,KAAK,WAAW,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACrE,MAAM,IAAI,KAAK,CAAC,qFAAqF,CAAC,CAAC;QACzG,CAAC;QACD,MAAM,MAAM,GAAG,mCAAmC,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC7E,IAAI,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,UAAU,CAAC;YAChB,OAAO,EAAE,CAAC;YACV,GAAG,MAAM;YACT,OAAO;YACP,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC;YACtB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,GAAW;IACvC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClG,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE;WACjD,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,SAAS,CAAC;WAC9D,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;WAC3C,CAAC,UAAU,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,SAAS,CAAC,EAAE,CAAC;QACpG,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,MAAM,GAAmD,MAAM,CAAC,MAAM,CAAC;QAC3E,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC;QACpD,IAAI;QACJ,EAAE;QACF,GAAG,CAAC,UAAU,IAAI,QAAQ;YACxB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;oBACtB,IAAI,EAAE,UAA6C;oBACnD,EAAE,EAAE,QAAQ;iBACb,CAAC,EAAE;YACN,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClC,CAAC,CAAC;IACH,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,eAAe,CAAC,MAAgC;IACvD,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;WACxC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,qCAAqC,EAAE,CAAC;QACtF,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IACD,WAAW,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,qBAAqB,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACnF,CAAC;IACD,WAAW,CAAC,QAAQ,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,SAAS,CAAC,KAA8D;IAC/E,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ;SAC1B,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC;SAC1C,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAE,OAAO,CAAC,IAAqC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;SACjF,IAAI,CAAC,EAAE,CAAC;SACR,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,KAAa;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,KAAK,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QACzE,MAAM,IAAI,KAAK,CAAC,wBAAwB,KAAK,yBAAyB,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/lib/workroom/human-ingress.d.ts

@@ -0,0 +1,182 @@
+import type { InteractionSpaceDecision } from './interaction-space-router.js';
+import { type ConversationRef } from '@zhin.js/im-contract';
+export type HumanIngressIntent = 'discussion' | 'work_request' | 'control';
+export type HumanIngressSpaceDecision = Readonly<Extract<InteractionSpaceDecision, {
+    status: 'resolved';
+    source: 'binding';
+}> & {
+    readonly space: 'workroom' | 'sponsor_room';
+    readonly projectId: string;
+}>;
+export interface HumanIngressConversationEventRef {
+    readonly version: 1;
+    readonly ref: string;
+    readonly digest: string;
+    readonly sequence: number;
+    readonly conversation: ConversationRef;
+}
+export interface HumanPrincipalSnapshot {
+    readonly version: 1;
+    readonly ref: string;
+    readonly revision: number;
+    readonly digest: string;
+    readonly principalId: string;
+    readonly subjectId: string;
+    readonly kind: 'human';
+}
+export interface HumanIngressProposalInput {
+    readonly decision: HumanIngressSpaceDecision;
+    readonly sourceEvent: HumanIngressConversationEventRef;
+    readonly principal: HumanPrincipalSnapshot;
+    /** Catalog-selected Agent definition that owns the Project Inbox. */
+    readonly entryAgentDefinitionId?: string;
+}
+export type HumanIngressTargetResolutionRequest = Readonly<HumanIngressProposalInput>;
+export interface HumanIngressTaskTarget {
+    readonly projectId: string;
+    readonly runId: string;
+    readonly taskKey: string;
+    readonly taskRevision: number;
+    readonly assignmentId?: string;
+    readonly assignmentRevision?: number;
+    readonly agentDefinitionId?: string;
+    readonly status: 'active' | 'historical';
+}
+/** Durable proof that a Sponsor control replied to a governed single-Project projection. */
+export interface HumanIngressProjectionReplyProof {
+    readonly version: 1;
+    readonly projectionId: string;
+    readonly projectId: string;
+    readonly bindingRevision: number;
+    readonly messageKey: string;
+    readonly targetDigest: string;
+}
+interface HumanIngressTargetResolutionEcho extends HumanIngressTargetResolutionRequest {
+    readonly intent: HumanIngressIntent;
+    readonly resolverRef: string;
+    readonly resolverDigest: string;
+}
+export type HumanIngressTargetResolution = Readonly<HumanIngressTargetResolutionEcho & {
+    readonly status: 'unaddressed';
+    readonly projectionReply?: HumanIngressProjectionReplyProof;
+}> | Readonly<HumanIngressTargetResolutionEcho & {
+    readonly status: 'task_target';
+    readonly via: 'reply' | 'mention';
+    readonly target: HumanIngressTaskTarget;
+}> | Readonly<HumanIngressTargetResolutionEcho & {
+    readonly status: 'clarification_required';
+    readonly reason: 'target_not_found' | 'ambiguous_target' | 'cross_project_target';
+    readonly candidateRefs: readonly string[];
+}>;
+export interface HumanIngressTargetResolverPort {
+    resolve(request: HumanIngressTargetResolutionRequest): HumanIngressTargetResolution | Promise<HumanIngressTargetResolution>;
+}
+export interface HumanIngressSourceAnchor {
+    readonly ref: string;
+    readonly digest: string;
+    readonly sequence: number;
+    readonly conversationKey: string;
+}
+export interface HumanIngressPrincipalReference {
+    readonly ref: string;
+    readonly revision: number;
+    readonly digest: string;
+    readonly principalId: string;
+    readonly subjectId: string;
+}
+export type HumanIngressAuthorityRequirement = 'none' | 'workroom_control' | 'typed_sponsor_control';
+interface HumanIngressProposalBase {
+    readonly version: 1;
+    readonly id: string;
+    readonly digest: string;
+    readonly status: 'proposed';
+    readonly projectId: string;
+    readonly space: 'workroom' | 'sponsor_room';
+    readonly bindingRevision: number;
+    readonly bindingDigest: string;
+    readonly sourceEvent: HumanIngressSourceAnchor;
+    readonly principal: HumanIngressPrincipalReference;
+    readonly intent: HumanIngressIntent;
+    readonly resolverRef: string;
+    readonly resolverDigest: string;
+    readonly authorityRequirement: HumanIngressAuthorityRequirement;
+    readonly projectionReply?: HumanIngressProjectionReplyProof;
+}
+export interface ProjectInboxProposal extends HumanIngressProposalBase {
+    readonly kind: 'project_inbox';
+    readonly target: Readonly<{
+        readonly orchestrator: true;
+        readonly agentDefinitionId?: string;
+    }>;
+}
+export interface TaskInputProposal extends HumanIngressProposalBase {
+    readonly kind: 'task_input';
+    readonly via: 'reply' | 'mention';
+    readonly target: HumanIngressTaskTarget;
+    readonly disposition: 'context_proposal' | 'discussion_only';
+}
+export type HumanIngressProposal = ProjectInboxProposal | TaskInputProposal;
+export interface HumanIngressProposalEventDraft {
+    readonly eventId: string;
+    readonly type: 'project_inbox.proposed' | 'task_input.proposed';
+    readonly proposal: HumanIngressProposal;
+}
+export interface HumanIngressProposalEvent extends HumanIngressProposalEventDraft {
+    readonly version: 1;
+    readonly projectId: string;
+    readonly sequence: number;
+    readonly digest: string;
+}
+export interface HumanIngressProposalProjection {
+    readonly version: 1;
+    readonly projectId: string;
+    readonly sequence: number;
+    readonly inbox: readonly ProjectInboxProposal[];
+    readonly taskInputs: readonly TaskInputProposal[];
+}
+export interface HumanIngressProposalRepository {
+    read(projectId: string): Promise<readonly HumanIngressProposalEvent[]>;
+    append(projectId: string, expectedSequence: number, drafts: readonly HumanIngressProposalEventDraft[]): Promise<readonly HumanIngressProposalEvent[]>;
+}
+export declare class HumanIngressProposalSequenceConflictError extends Error {
+    readonly projectId: string;
+    readonly expectedSequence: number;
+    readonly actualSequence: number;
+    constructor(projectId: string, expectedSequence: number, actualSequence: number);
+}
+export declare class HumanIngressProposalReplayConflictError extends Error {
+    readonly projectId: string;
+    readonly proposalId?: string | undefined;
+    constructor(projectId: string, proposalId?: string | undefined);
+}
+/**
+ * Contract adapter for tests and embedders. This adapter is process-local and
+ * is explicitly not a production-durable Workroom Inbox.
+ */
+export declare class MemoryHumanIngressProposalRepository implements HumanIngressProposalRepository {
+    #private;
+    read(projectId: string): Promise<readonly HumanIngressProposalEvent[]>;
+    append(projectId: string, expectedSequence: number, drafts: readonly HumanIngressProposalEventDraft[]): Promise<readonly HumanIngressProposalEvent[]>;
+}
+export type HumanIngressProposalOutcome = Readonly<{
+    status: 'proposed';
+    duplicate: boolean;
+    event: HumanIngressProposalEvent;
+    projection: HumanIngressProposalProjection;
+}> | Readonly<{
+    status: 'clarification_required';
+    sourceEventRef: string;
+    reason: Extract<HumanIngressTargetResolution, {
+        status: 'clarification_required';
+    }>['reason'];
+    candidateRefs: readonly string[];
+}>;
+/** Produces content-free proposals only; it has no Workroom Kernel command port. */
+export declare class HumanIngressProposalService {
+    readonly repository: HumanIngressProposalRepository;
+    readonly targetResolver: HumanIngressTargetResolverPort;
+    constructor(repository: HumanIngressProposalRepository, targetResolver: HumanIngressTargetResolverPort);
+    propose(input: HumanIngressProposalInput): Promise<HumanIngressProposalOutcome>;
+}
+export {};
+//# sourceMappingURL=human-ingress.d.ts.map

package/lib/workroom/human-ingress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-ingress.d.ts","sourceRoot":"","sources":["../../src/workroom/human-ingress.ts"],"names":[],"mappings":"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"}