@ixo/flow-work 0.3.0 → 0.4.1

package/README.md

@@ -2,16 +2,111 @@
 
 [![npm version](https://img.shields.io/npm/v/%40ixo%2Fflow-work)](https://www.npmjs.com/package/@ixo/flow-work)
 
-Oracle-side flow-work plugin: accept UCAN-delegated `ixo.flow.work` invocations
-from the IXO flow-manager over Matrix and post receipts.
+Helper-oracle-side flow-work plugin: accept UCAN-delegated `ixo.flow.work`
+invocations from the IXO flow-manager over Matrix and post receipts.
 
-It is the oracle half of the flow-work contract. Flow-manager discovers a
-capable oracle, mints a UCAN delegation scoped to a flow node, and sends an
-`ixo.flow.work.invoke` event carrying the work brief by value. `FlowWorkListener`
-validates the delegation (audience, expiry, signature chain, nb caveats),
-runs the matching capability handler, and posts an `ixo.flow.work.receipt`.
-The oracle never gains read authority over anything — inputs arrive in the
-invocation, the result leaves in the receipt.
+It is the helper half of the flow-work contract. Flow-manager discovers a
+capable helper-oracle, mints a UCAN delegation scoped to a flow node, and sends
+an `ixo.flow.work.invoke` event carrying the work brief by value.
+`FlowWorkListener` validates the delegation (audience, expiry, signature chain,
+nb caveats), runs the matching capability handler, and posts an
+`ixo.flow.work.receipt`. The helper-oracle never gains general read authority
+over the flow document: inputs arrive in the invocation and the result leaves
+in the receipt.
+
+## Keep the two oracle paths separate
+
+An IXO **standard oracle** is user-facing, typically a chat or AI agent.
+Flow-manager is one standard oracle among many; it also contracts work as an
+orchestrator. Standard oracles use the existing standard-oracle Composio UCAN
+path.
+
+A **helper-oracle** is a non-user-facing specialist, such as `xero-oracle` or
+`diagnostic-oracle`. A user does not technically contact it. Flow-manager hires
+it through a flow-work contract, and it is the terminal executor of that
+contract.
+
+`@ixo/flow-work` exists only for the helper-oracle path. It must not intercept,
+replace, or reinterpret the standard-oracle chat/Composio path.
+
+```text
+standard path: user <-> standard oracle <-> standard-oracle Composio path
+
+helper path:   user -> flow-manager -> @ixo/flow-work helper -> downstream service
+```
+
+## Calling a downstream service
+
+A work contract and downstream authority are different capabilities:
+
+- The flow-work capability authorizes one helper task on one flow node.
+- A supplementary capability, when required, authorizes the helper to call a
+  particular downstream service.
+
+For Composio work, flow-manager adds the user's existing `composio/proxy`
+capability for one concrete entity to the helper-addressed delegation. It does
+not derive that authority from Matrix content, caveats, or the helper's API
+key. The helper then passes the validated flow-work delegation to the ambient
+oracle-runtime UCAN minter:
+
+```ts
+import type { FlowWorkCapability } from '@ixo/flow-work';
+
+const capability: FlowWorkCapability = {
+  can: 'flow/xero.invoice.create',
+  actionType: 'xero_invoice_create',
+  description: 'Create one Xero invoice',
+  inputSchema,
+  handler: async (inputs, context) => {
+    const composioResource = context.contractCaveats.composioResource;
+    if (typeof composioResource !== 'string') {
+      throw new Error('The contract has no Composio entity resource.');
+    }
+    const remainingSeconds = Math.floor(
+      (context.deadline - Date.now()) / 1_000,
+    );
+    if (remainingSeconds <= 0) {
+      throw new Error('The flow-work contract has expired.');
+    }
+
+    const minted = await getUcan().createInvocationFromDelegation(
+      context.delegation,
+      composioWorkerUrl,
+      {
+        can: 'composio/proxy',
+        with: composioResource,
+      },
+      { maxTtlSeconds: Math.min(120, remainingSeconds) },
+    );
+    if ('error' in minted) throw new Error(minted.error);
+
+    return callComposio(inputs, minted.invocation);
+  },
+};
+```
+
+The helper is responsible for failing closed unless:
+
+- the signed delegation is addressed to the contracted helper;
+- it carries that exact supplementary capability; and
+- the downstream invocation expires no later than the work deadline.
+
+The ambient minter verifies that the configured helper DID matches the
+delegation audience before signing and clamps to the requested TTL and
+delegation expiration. The helper must additionally clamp that requested TTL
+to `context.deadline`, as shown above. The downstream service cryptographically
+rejects capabilities the proof chain does not authorize. The resulting chain
+is:
+
+```text
+user --composio/proxy(entity)--> flow-manager
+     --flow-work + composio/proxy(entity)--> helper-oracle
+     --composio/proxy(entity) invocation--> Composio worker
+```
+
+The Composio API key identifies and can revoke the helper actor. It does not
+choose the user/entity tenant. A diagnostic helper receives no Composio grant
+unless its specific contract genuinely needs one.
 
 ## Install
 
@@ -22,6 +117,37 @@ pnpm add @ixo/flow-work
 Peer dependencies: `@ixo/oracle-runtime`, `@ixo/ucan`, `@nestjs/common`,
 `matrix-js-sdk`.
 
+## Requesting user input
+
+Capability handlers can pause for durable, structured human input in the flow
+room. Use a stable `requestKey` derived from the node and purpose, never the
+attempt's `invocationId`; retries then re-arm the same request instead of
+posting a duplicate.
+
+```ts
+async function handler(inputs: MyInputs, context: FlowWorkInvocationContext) {
+  const outcome = await context.input.request({
+    requestKey: `${context.nodeId}:approve-payment`,
+    template: 'approval',
+    prompt: `Pay invoice ${inputs.invoiceId} (${inputs.amount})?`,
+    deadline: Date.now() + 4 * 60 * 60 * 1000,
+  });
+
+  if (outcome.status === 'expired' || !outcome.response.approved) {
+    return {
+      approved: false,
+      reason: outcome.status === 'expired' ? 'timeout' : 'declined',
+    };
+  }
+  return pay(inputs);
+}
+```
+
+The `approval`, `select`, `entity-select`, and `text` templates are exported
+from the browser-safe `@ixo/flow-work/input` subpath. An attempt-window closure
+is retried by flow-manager automatically; an actual request deadline resolves
+as `{ status: 'expired' }` so the handler can return a domain result.
+
 ## Releasing
 
 This package versions independently of the flow-manager app via

package/dist/capability.d.ts

@@ -1,4 +1,11 @@
 import type { z } from 'zod';
+import type { InputOutcomeFor, RequestUserInputParams } from './input-requests.js';
+import type { FlowWorkInputTemplate } from './input.js';
+export interface FlowWorkInputApi {
+    request<T extends FlowWorkInputTemplate>(params: Extract<RequestUserInputParams, {
+        template: T;
+    }>): Promise<InputOutcomeFor<T>>;
+}
 /**
  * What the listener hands a capability handler alongside its validated inputs:
  * the invocation's identity and the UCAN delegation that authorized it. The
@@ -6,11 +13,12 @@ import type { z } from 'zod';
  * before the handler runs — this context is for handlers that need to *act* on
  * it, not re-check it.
  *
- * A handler that calls a downstream UCAN-guarded service (e.g. the Composio
- * worker) uses `delegation` to re-mint a fresh, service-targeted invocation
- * from the same authorization chain, or mints a self-signed one when it acts
- * as the oracle itself. `invocationId` / `nodeId` are the natural idempotency
- * key for writes bound to a single flow node.
+ * A helper-oracle handler that calls a downstream UCAN-guarded service (e.g.
+ * the Composio worker) passes `delegation` to the oracle runtime's ambient
+ * `createInvocationFromDelegation` minter. That creates a fresh invocation
+ * signed by the helper while retaining the user-rooted authorization chain.
+ * `invocationId` / `nodeId` are the natural idempotency key for writes bound
+ * to a single flow node.
  */
 export interface FlowWorkInvocationContext {
     /** Unique id of this invocation — stable across redelivery. */
@@ -35,12 +43,14 @@ export interface FlowWorkInvocationContext {
     /** This oracle's DID — the delegation audience. */
     audience: string;
     /**
-     * The serialized UCAN delegation (base64 CAR) that authorized this
-     * invocation, already validated by the listener. Pass it to
-     * `ucan.createInvocationFromDelegation(...)` to act on the delegator's
-     * behalf against a downstream service.
+     * The serialized UCAN delegation (base64 CAR) already validated by the
+     * listener. It always carries the flow-work grant and may also carry
+     * separately proven supplementary grants for downstream services. Do not
+     * treat Matrix inputs or `contractCaveats` as authority.
      */
     delegation: string;
+    /** Ask a human for structured input in the invocation's Matrix room. */
+    input: FlowWorkInputApi;
 }
 /**
  * A contractable capability: the unit of work this oracle accepts from
@@ -72,7 +82,8 @@ export interface FlowWorkCapability<Schema extends z.ZodType = z.ZodType> {
     /**
      * Runs the work. Receives the validated inputs and the invocation context.
      * Pure, self-contained handlers (no downstream auth) may ignore the second
-     * argument; handlers that call UCAN-guarded services use its `delegation`.
+     * argument; handlers that call UCAN-guarded services pass its `delegation`
+     * to the oracle runtime's ambient UCAN minter.
      */
     handler: (inputs: z.infer<Schema>, context: FlowWorkInvocationContext) => Promise<unknown>;
 }

package/dist/capability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IACtE,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACzB;;;;OAIG;IACH,OAAO,EAAE,CACP,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EACvB,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,kBAAkB,GAAG,SAAS,CAIhC"}
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,CAAC,SAAS,qBAAqB,EACrC,MAAM,EAAE,OAAO,CAAC,sBAAsB,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAA;KAAE,CAAC,GACvD,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IACtE,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACzB;;;;;OAKG;IACH,OAAO,EAAE,CACP,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EACvB,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,kBAAkB,GAAG,SAAS,CAIhC"}

package/dist/capability.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAoFA,MAAM,UAAU,cAAc,CAC5B,YAA2C,EAC3C,GAAW,EACX,UAAkB;IAElB,OAAO,YAAY,CAAC,IAAI,CACtB,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,IAAI,KAAK,CAAC,UAAU,KAAK,UAAU,CAChE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAmGA,MAAM,UAAU,cAAc,CAC5B,YAA2C,EAC3C,GAAW,EACX,UAAkB;IAElB,OAAO,YAAY,CAAC,IAAI,CACtB,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,IAAI,KAAK,CAAC,UAAU,KAAK,UAAU,CAChE,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { FlowWorkPlugin, type FlowWorkPluginOptions, } from './flow-work.plugin.js';
-export { findCapability, type FlowWorkCapability, type FlowWorkInvocationContext, } from './capability.js';
-export { FlowWorkListener } from './listener.js';
+export { findCapability, type FlowWorkCapability, type FlowWorkInputApi, type FlowWorkInvocationContext, } from './capability.js';
+export { FlowWorkListener, type FlowWorkLogger } from './listener.js';
 export { adaptMatrixClient, type FlowWorkInvite, type FlowWorkMatrixPort, type FlowWorkRoomEvent, } from './matrix-port.js';
+export * from './input.js';
+export { FlowWorkInputError, InputRequestCoordinator, computeInputContentHash, requestStateKey, type FlowWorkInputErrorCode, type InputOutcome, type InputOutcomeFor, type RequestUserInputParams, } from './input-requests.js';
 export { FLOW_WORK_ASSIGN_EVENT, FLOW_WORK_BINDING_FIELDS, FLOW_WORK_INVOKE_EVENT, FLOW_WORK_READY_EVENT, FLOW_WORK_RECEIPT_EVENT, computeFlowWorkInputHash, flowWorkAssignSchema, flowWorkBindingSchema, flowWorkInvokeSchema, flowWorkNbFor, flowWorkReadySchema, flowWorkReceiptSchema, sameFlowWorkBinding, sameFlowWorkNb, type FlowWorkAssign, type FlowWorkBinding, type FlowWorkErrorCode, type FlowWorkInvoke, type FlowWorkNb, type FlowWorkReady, type FlowWorkReceipt, } from './protocol.js';
 export { buildDelegationValidator, type DelegationValidator } from './ucan.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -2,6 +2,8 @@ export { FlowWorkPlugin, } from './flow-work.plugin.js';
 export { findCapability, } from './capability.js';
 export { FlowWorkListener } from './listener.js';
 export { adaptMatrixClient, } from './matrix-port.js';
+export * from './input.js';
+export { FlowWorkInputError, InputRequestCoordinator, computeInputContentHash, requestStateKey, } from './input-requests.js';
 export { FLOW_WORK_ASSIGN_EVENT, FLOW_WORK_BINDING_FIELDS, FLOW_WORK_INVOKE_EVENT, FLOW_WORK_READY_EVENT, FLOW_WORK_RECEIPT_EVENT, computeFlowWorkInputHash, flowWorkAssignSchema, flowWorkBindingSchema, flowWorkInvokeSchema, flowWorkNbFor, flowWorkReadySchema, flowWorkReceiptSchema, sameFlowWorkBinding, sameFlowWorkNb, } from './protocol.js';
 export { buildDelegationValidator } from './ucan.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,GAGf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EACL,iBAAiB,GAIlB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,GAQf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAA4B,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,GAIf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAuB,MAAM,eAAe,CAAC;AACtE,OAAO,EACL,iBAAiB,GAIlB,MAAM,kBAAkB,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,GAKhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,GAQf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAA4B,MAAM,WAAW,CAAC"}

package/dist/input-requests.d.ts

@@ -0,0 +1,65 @@
+import type { FlowWorkLogger } from './listener.js';
+import type { FlowWorkMatrixPort } from './matrix-port.js';
+import { type FlowWorkInputRequest, type FlowWorkInputResponse, type FlowWorkInputTemplate } from './input.js';
+export type RequestUserInputParams = FlowWorkInputRequest extends infer R ? R extends FlowWorkInputRequest ? Omit<R, 'protocolVersion' | 'invocationId'> & {
+    signal?: AbortSignal;
+} : never : never;
+export type InputOutcomeFor<T extends FlowWorkInputTemplate> = {
+    status: 'answered';
+    response: Extract<FlowWorkInputResponse, {
+        template: T;
+    }>;
+    requestEventId: string;
+    responseEventId: string;
+    sender: string;
+    respondedAtMs: number;
+    fromHistory: boolean;
+} | {
+    status: 'expired';
+    requestEventId?: string;
+    deadline: number;
+};
+export type InputOutcome = InputOutcomeFor<FlowWorkInputTemplate>;
+export type FlowWorkInputErrorCode = 'invalid_request' | 'send_failed' | 'request_conflict' | 'await_window_closed' | 'aborted';
+export declare class FlowWorkInputError extends Error {
+    readonly code: FlowWorkInputErrorCode;
+    constructor(code: FlowWorkInputErrorCode, message: string);
+}
+export declare function requestStateKey(sender: string, nodeId: string, requestKey: string): string;
+export declare function computeInputContentHash(content: Omit<FlowWorkInputRequest, 'protocolVersion' | 'invocationId' | 'deadline'>): string;
+interface RequestScope {
+    roomId: string;
+    invocationId: string;
+    nodeId: string;
+    attempt: number;
+    inputHash: string;
+    bindingDeadline: number;
+}
+interface CoordinatorOptions {
+    port: FlowWorkMatrixPort;
+    logger: FlowWorkLogger;
+    now: () => number;
+    retryMs: number;
+}
+export declare class InputRequestCoordinator {
+    private readonly options;
+    private readonly pending;
+    private readonly inFlight;
+    private unsubscribe?;
+    private started;
+    private lifecycleController;
+    constructor(options: CoordinatorOptions);
+    start(): void;
+    stop(): void;
+    request<T extends FlowWorkInputTemplate>(scope: RequestScope, params: Extract<RequestUserInputParams, {
+        template: T;
+    }>): Promise<InputOutcomeFor<T>>;
+    private run;
+    private adoptRecentRequest;
+    private writeIndex;
+    private historyWinner;
+    private awaitResponse;
+    private retryMs;
+}
+export {};
+//# sourceMappingURL=input-requests.d.ts.map

package/dist/input-requests.d.ts.map

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