@sequenceholdings/agent-spec 0.1.1 → 0.1.3

package/dist/voice-actions-transitions.d.ts

@@ -0,0 +1,52 @@
+import { type VoiceActionIntentBinding, type VoiceActionIntentState, type VoiceActionIntentTransition, type VoiceCommittedActionReceipt, type VoicePrepareActionRequest, type VoicePreparedActionIntent } from './voice-actions-contracts.js';
+export type PrepareVoiceActionIntentResult = {
+    outcome: 'prepared';
+    state: VoicePreparedActionIntent;
+} | {
+    outcome: 'retry';
+    state: VoiceActionIntentState;
+} | {
+    outcome: 'conflict';
+    reason: 'intent_binding_conflict';
+};
+export declare function prepareVoiceActionIntent({ request, existing }: {
+    request: VoicePrepareActionRequest;
+    existing: VoiceActionIntentState | null;
+}): PrepareVoiceActionIntentResult;
+export type VoiceActionConfirmationDecision = {
+    decision: 'dispatch';
+} | {
+    decision: 'reconcile';
+    reason: 'uncertain_outcome';
+} | {
+    decision: 'return_receipt';
+    receipt: VoiceCommittedActionReceipt;
+} | {
+    decision: 'conflict';
+    reason: 'intent_binding_conflict';
+} | {
+    decision: 'denied';
+    reason: 'intent_cancelled' | 'intent_expired';
+};
+export declare function decideVoiceActionConfirmation({ state, binding, now }: {
+    state: VoiceActionIntentState;
+    binding: VoiceActionIntentBinding;
+    now: string;
+}): VoiceActionConfirmationDecision;
+export type TransitionVoiceActionIntentResult = {
+    outcome: 'transitioned';
+    state: VoiceActionIntentState;
+} | {
+    outcome: 'retry';
+    state: VoiceActionIntentState;
+} | {
+    outcome: 'conflict';
+    reason: 'intent_binding_conflict' | 'terminal_receipt_conflict';
+} | {
+    outcome: 'denied';
+    reason: 'intent_expired' | 'terminal_intent' | 'uncertain_requires_reconciliation';
+};
+export declare function transitionVoiceActionIntent({ state, transition }: {
+    state: VoiceActionIntentState;
+    transition: VoiceActionIntentTransition;
+}): TransitionVoiceActionIntentResult;

package/dist/voice-actions-transitions.js

@@ -0,0 +1,170 @@
+import { voiceTimestampSchema } from './voice-common.js';
+import { sameVoiceResource } from './voice-authority-contracts.js';
+import { voiceActionIntentBindingSchema, voiceActionIntentStateSchema, voiceActionIntentTransitionSchema, voicePrepareActionRequestSchema, voicePreparedActionIntentSchema, } from './voice-actions-contracts.js';
+function sameCallSubject({ left, right }) {
+    return left.tenantId === right.tenantId &&
+        left.environmentId === right.environmentId &&
+        left.agentId === right.agentId &&
+        left.sessionId === right.sessionId &&
+        left.releaseId === right.releaseId;
+}
+function sameAuthoritySubject({ left, right }) {
+    if (left.kind !== right.kind)
+        return false;
+    if (left.kind === 'unverified' || right.kind === 'unverified') {
+        return left.kind === right.kind;
+    }
+    return sameVoiceResource({ left: left.resource, right: right.resource }) &&
+        left.verificationId === right.verificationId;
+}
+function bindingFromState({ state }) {
+    return {
+        intentId: state.intentId,
+        subject: state.subject,
+        actionAlias: state.actionAlias,
+        authoritySubject: state.authoritySubject,
+        argumentDigest: state.argumentDigest,
+    };
+}
+function sameIntentBinding({ left, right }) {
+    return left.intentId === right.intentId &&
+        sameCallSubject({ left: left.subject, right: right.subject }) &&
+        left.actionAlias === right.actionAlias &&
+        sameAuthoritySubject({ left: left.authoritySubject, right: right.authoritySubject }) &&
+        left.argumentDigest === right.argumentDigest;
+}
+export function prepareVoiceActionIntent({ request, existing }) {
+    const parsedRequest = voicePrepareActionRequestSchema.parse(request);
+    if (existing !== null) {
+        const parsedExisting = voiceActionIntentStateSchema.parse(existing);
+        return sameIntentBinding({
+            left: bindingFromState({ state: parsedExisting }), right: parsedRequest.binding,
+        })
+            ? { outcome: 'retry', state: parsedExisting }
+            : { outcome: 'conflict', reason: 'intent_binding_conflict' };
+    }
+    return {
+        outcome: 'prepared',
+        state: voicePreparedActionIntentSchema.parse({
+            ...parsedRequest.binding, state: 'prepared',
+            confirmationSummary: parsedRequest.confirmationSummary,
+            preparedAt: parsedRequest.preparedAt, expiresAt: parsedRequest.expiresAt,
+        }),
+    };
+}
+export function decideVoiceActionConfirmation({ state, binding, now }) {
+    const parsedState = voiceActionIntentStateSchema.parse(state);
+    const parsedBinding = voiceActionIntentBindingSchema.parse(binding);
+    const parsedNow = voiceTimestampSchema.parse(now);
+    if (!sameIntentBinding({ left: bindingFromState({ state: parsedState }),
+        right: parsedBinding })) {
+        return { decision: 'conflict', reason: 'intent_binding_conflict' };
+    }
+    if (parsedState.state === 'committed') {
+        return { decision: 'return_receipt', receipt: parsedState };
+    }
+    if (parsedState.state === 'cancelled') {
+        return { decision: 'denied', reason: 'intent_cancelled' };
+    }
+    if (parsedState.state === 'uncertain') {
+        return { decision: 'reconcile', reason: 'uncertain_outcome' };
+    }
+    return Date.parse(parsedNow) >= Date.parse(parsedState.expiresAt)
+        ? { decision: 'denied', reason: 'intent_expired' }
+        : { decision: 'dispatch' };
+}
+function sameCommittedReceipt({ state, transition }) {
+    return state.receiptId === transition.receiptId &&
+        state.resultDigest === transition.resultDigest &&
+        state.resultStatus === transition.resultStatus &&
+        state.committedAt === transition.occurredAt;
+}
+function sameCancellationReceipt({ state, transition }) {
+    return state.cancellationReceiptId === transition.cancellationReceiptId &&
+        state.cancellationResolution === transition.resolution &&
+        state.cancelledAt === transition.occurredAt;
+}
+function terminalTransition({ state, transition }) {
+    if (state.state === 'committed') {
+        if (transition.kind !== 'commit')
+            return { outcome: 'denied', reason: 'terminal_intent' };
+        return sameCommittedReceipt({ state, transition })
+            ? { outcome: 'retry', state }
+            : { outcome: 'conflict', reason: 'terminal_receipt_conflict' };
+    }
+    if (state.state === 'cancelled') {
+        if (transition.kind !== 'cancel')
+            return { outcome: 'denied', reason: 'terminal_intent' };
+        return sameCancellationReceipt({ state, transition })
+            ? { outcome: 'retry', state }
+            : { outcome: 'conflict', reason: 'terminal_receipt_conflict' };
+    }
+    return null;
+}
+function uncertaintyTransition({ state, transition }) {
+    if (state.state === 'uncertain') {
+        const same = state.dispatchAttemptId === transition.dispatchAttemptId &&
+            state.uncertainAt === transition.occurredAt;
+        return same ? { outcome: 'retry', state }
+            : { outcome: 'denied', reason: 'uncertain_requires_reconciliation' };
+    }
+    if (Date.parse(transition.occurredAt) >= Date.parse(state.expiresAt)) {
+        return { outcome: 'denied', reason: 'intent_expired' };
+    }
+    return {
+        outcome: 'transitioned',
+        state: {
+            ...bindingFromState({ state }), state: 'uncertain',
+            confirmationSummary: state.confirmationSummary, preparedAt: state.preparedAt,
+            expiresAt: state.expiresAt, dispatchAttemptId: transition.dispatchAttemptId,
+            uncertainAt: transition.occurredAt,
+        },
+    };
+}
+function commitTransition({ state, transition }) {
+    const expired = state.state === 'prepared' &&
+        Date.parse(transition.occurredAt) >= Date.parse(state.expiresAt);
+    if (expired)
+        return { outcome: 'denied', reason: 'intent_expired' };
+    return {
+        outcome: 'transitioned',
+        state: {
+            ...bindingFromState({ state }), state: 'committed', receiptId: transition.receiptId,
+            resultDigest: transition.resultDigest, resultStatus: transition.resultStatus,
+            committedAt: transition.occurredAt,
+        },
+    };
+}
+function cancelTransition({ state, transition }) {
+    const invalid = (state.state === 'uncertain' && transition.resolution !== 'confirmed_not_committed') ||
+        (state.state === 'prepared' && transition.resolution !== 'local_before_dispatch');
+    if (invalid)
+        return { outcome: 'denied', reason: 'uncertain_requires_reconciliation' };
+    return {
+        outcome: 'transitioned',
+        state: {
+            ...bindingFromState({ state }), state: 'cancelled',
+            cancellationReceiptId: transition.cancellationReceiptId,
+            cancellationResolution: transition.resolution, cancelledAt: transition.occurredAt,
+        },
+    };
+}
+export function transitionVoiceActionIntent({ state, transition }) {
+    const parsedState = voiceActionIntentStateSchema.parse(state);
+    const parsedTransition = voiceActionIntentTransitionSchema.parse(transition);
+    if (!sameIntentBinding({ left: bindingFromState({ state: parsedState }),
+        right: parsedTransition.binding })) {
+        return { outcome: 'conflict', reason: 'intent_binding_conflict' };
+    }
+    if (parsedState.state === 'committed' || parsedState.state === 'cancelled') {
+        const terminal = terminalTransition({ state: parsedState, transition: parsedTransition });
+        return terminal ?? { outcome: 'denied', reason: 'terminal_intent' };
+    }
+    if (parsedTransition.kind === 'mark_uncertain') {
+        return uncertaintyTransition({ state: parsedState, transition: parsedTransition });
+    }
+    if (parsedTransition.kind === 'commit') {
+        return commitTransition({ state: parsedState, transition: parsedTransition });
+    }
+    return cancelTransition({ state: parsedState, transition: parsedTransition });
+}

package/dist/voice-actions.d.ts

@@ -0,0 +1,2 @@
+export * from './voice-actions-contracts.js';
+export * from './voice-actions-transitions.js';

package/dist/voice-actions.js

@@ -0,0 +1,2 @@
+export * from './voice-actions-contracts.js';
+export * from './voice-actions-transitions.js';