@zhin.js/workroom 0.0.0 → 0.0.2

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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"}