@guyghost/swarm-dao-core 0.3.0 → 0.5.0

package/dist/governance/delegation.machine.d.ts

@@ -0,0 +1,316 @@
+import type { AgentOutput, DAOAgent, DelegationProfileEntry } from "../types/index.js";
+export type DelegationCoordinatorStatus = "open" | "blocked_signal" | "draining" | "closed";
+export type DelegationRequestStatus = "requested" | "gated" | "spawned" | "reported" | "delegated" | "blocked" | "cancelled" | "failed";
+export declare const COORDINATOR_FINAL_STATUSES: ReadonlySet<DelegationCoordinatorStatus>;
+export declare const REQUEST_FINAL_STATUSES: ReadonlySet<DelegationRequestStatus>;
+export declare function isCoordinatorFinal(status: DelegationCoordinatorStatus): boolean;
+export declare function isDelegationRequestFinal(status: DelegationRequestStatus): boolean;
+/**
+ * Normalize a facet token. Pure. The orchestrator MUST call this before
+ * emitting REQUEST_ARRIVED; guards match on the normalized value exactly.
+ */
+export declare function normalizeFacet(facet: string): string;
+/**
+ * Reasons the per-request gate can cite. Pure function — the single authority
+ * for facet/archetype/depth authorization (INV-2). The machine's `gateApproved`
+ * guard trusts `ok`; the orchestrator is the only sanctioned dispatcher.
+ */
+export interface DelegationGateResult {
+    ok: boolean;
+    reasons: string[];
+}
+export interface DelegationGateInput {
+    facet: string;
+    archetype: string;
+    parentDepth: number;
+    maxDepth: number;
+    /** Declared capabilities of the parent agent. */
+    declared: readonly {
+        facet: string;
+        archetype: string;
+    }[];
+    /** Archetypes with a registered profile. */
+    registeredArchetypes: ReadonlySet<string>;
+}
+export declare function evaluateDelegationGate(input: DelegationGateInput): DelegationGateResult;
+/**
+ * INV-6 boundary marker — the hash the orchestrator must compute when it
+ * merges a child output into the parent's reasoning. Verified by the
+ * `reported → delegated` guard before the fold is acknowledged.
+ */
+export declare function computeMergedFoldHash(mergedContent: string): string;
+/**
+ * Extract a delegation signal from a parent agent's output. Pure. The ONLY
+ * place an LLM influences delegation. Returns one signal per recognized
+ * directive; malformed directives are ignored (they become REQUEST_REJECTED
+ * upstream, never REQUEST_ARRIVED — W2).
+ *
+ * Recognized format (sibling section, not inside `## Vote`):
+ *
+ *   ## Delegation Requests
+ *   - facet: <token> | archetype: <token>
+ */
+export interface DelegationSignal {
+    facet: string;
+    archetype: string;
+}
+export declare function extractDelegationSignals(content: string | undefined): DelegationSignal[];
+export interface DelegationCoordinatorContext {
+    parentAgentId: string;
+    parentDepth: number;
+    parentEnabled: boolean;
+    maxChildren: number;
+    maxDepth: number;
+    activeRequests: number;
+    lastTransitionTime: string;
+    errorMessage?: string;
+}
+export interface DelegationCoordinatorInput extends Omit<DelegationCoordinatorContext, "lastTransitionTime"> {
+    lastTransitionTime?: string;
+}
+export type DelegationCoordinatorEvent = {
+    type: "REQUEST_ARRIVED";
+    requestId: string;
+    facet: string;
+    archetype: string;
+} | {
+    type: "REQUEST_RESOLVED";
+    requestId: string;
+    terminalStatus: DelegationRequestStatus;
+} | {
+    type: "DRAIN";
+    reason: string;
+} | {
+    type: "ERROR";
+    message: string;
+};
+declare function buildCoordinatorMachine(initial: DelegationCoordinatorStatus): import("xstate").StateMachine<DelegationCoordinatorContext, {
+    type: "REQUEST_ARRIVED";
+    requestId: string;
+    facet: string;
+    archetype: string;
+} | {
+    type: "REQUEST_RESOLVED";
+    requestId: string;
+    terminalStatus: DelegationRequestStatus;
+} | {
+    type: "DRAIN";
+    reason: string;
+} | {
+    type: "ERROR";
+    message: string;
+}, {}, never, never, {
+    type: "parentEnabled";
+    params: unknown;
+} | {
+    type: "slotAvailable";
+    params: unknown;
+} | {
+    type: "depthWithinBudget";
+    params: unknown;
+} | {
+    type: "requestAccepted";
+    params: unknown;
+} | {
+    type: "lastInFlight";
+    params: unknown;
+}, never, "open" | "blocked_signal" | "draining" | "closed", string, DelegationCoordinatorInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "delegationCoordinator";
+    states: {
+        readonly open: {};
+        readonly draining: {};
+        readonly blocked_signal: {};
+        readonly closed: {};
+    };
+}>;
+export declare function createDelegationCoordinatorMachine(initial: DelegationCoordinatorStatus): import("xstate").StateMachine<DelegationCoordinatorContext, {
+    type: "REQUEST_ARRIVED";
+    requestId: string;
+    facet: string;
+    archetype: string;
+} | {
+    type: "REQUEST_RESOLVED";
+    requestId: string;
+    terminalStatus: DelegationRequestStatus;
+} | {
+    type: "DRAIN";
+    reason: string;
+} | {
+    type: "ERROR";
+    message: string;
+}, {}, never, never, {
+    type: "parentEnabled";
+    params: unknown;
+} | {
+    type: "slotAvailable";
+    params: unknown;
+} | {
+    type: "depthWithinBudget";
+    params: unknown;
+} | {
+    type: "requestAccepted";
+    params: unknown;
+} | {
+    type: "lastInFlight";
+    params: unknown;
+}, never, "open" | "blocked_signal" | "draining" | "closed", string, DelegationCoordinatorInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "delegationCoordinator";
+    states: {
+        readonly open: {};
+        readonly draining: {};
+        readonly blocked_signal: {};
+        readonly closed: {};
+    };
+}>;
+export type DelegationCoordinatorMachine = ReturnType<typeof buildCoordinatorMachine>;
+export interface DelegationRequestContext {
+    requestId: string;
+    parentAgentId: string;
+    facet: string;
+    archetype: string;
+    childAgentId?: string;
+    mergedAgentOutputHash?: string;
+    errorMessage?: string;
+    gateReasons: string[];
+    lastTransitionTime: string;
+}
+export interface DelegationRequestInput extends Omit<DelegationRequestContext, "lastTransitionTime"> {
+    lastTransitionTime?: string;
+}
+export type DelegationRequestEvent = {
+    type: "GATE_DECIDED";
+    ok: boolean;
+    reasons: string[];
+} | {
+    type: "SPAWN_ACKED";
+    childAgentId: string;
+} | {
+    type: "CHILD_REPORTED";
+    output: AgentOutput;
+} | {
+    type: "CHILD_FAILED";
+    error: string;
+} | {
+    type: "SPAWN_FAILED";
+    error: string;
+} | {
+    type: "FOLD_COMPLETE";
+    foldedInto: string;
+    mergedAgentOutputHash: string;
+} | {
+    type: "FOLD_TIMEOUT";
+} | {
+    type: "CANCEL";
+    reason: string;
+} | {
+    type: "ERROR";
+    message: string;
+};
+declare function buildRequestMachine(initial: DelegationRequestStatus): import("xstate").StateMachine<DelegationRequestContext, {
+    type: "GATE_DECIDED";
+    ok: boolean;
+    reasons: string[];
+} | {
+    type: "SPAWN_ACKED";
+    childAgentId: string;
+} | {
+    type: "CHILD_REPORTED";
+    output: AgentOutput;
+} | {
+    type: "CHILD_FAILED";
+    error: string;
+} | {
+    type: "SPAWN_FAILED";
+    error: string;
+} | {
+    type: "FOLD_COMPLETE";
+    foldedInto: string;
+    mergedAgentOutputHash: string;
+} | {
+    type: "FOLD_TIMEOUT";
+} | {
+    type: "CANCEL";
+    reason: string;
+} | {
+    type: "ERROR";
+    message: string;
+}, {}, never, never, {
+    type: "gateApproved";
+    params: unknown;
+} | {
+    type: "foldHashMatches";
+    params: unknown;
+}, never, "failed" | "requested" | "gated" | "spawned" | "reported" | "delegated" | "blocked" | "cancelled", string, DelegationRequestInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "delegationRequest";
+    states: {
+        readonly requested: {};
+        readonly gated: {};
+        readonly spawned: {};
+        readonly reported: {};
+        readonly delegated: {};
+        readonly blocked: {};
+        readonly cancelled: {};
+        readonly failed: {};
+    };
+}>;
+export declare function createDelegationRequestMachine(initial: DelegationRequestStatus): import("xstate").StateMachine<DelegationRequestContext, {
+    type: "GATE_DECIDED";
+    ok: boolean;
+    reasons: string[];
+} | {
+    type: "SPAWN_ACKED";
+    childAgentId: string;
+} | {
+    type: "CHILD_REPORTED";
+    output: AgentOutput;
+} | {
+    type: "CHILD_FAILED";
+    error: string;
+} | {
+    type: "SPAWN_FAILED";
+    error: string;
+} | {
+    type: "FOLD_COMPLETE";
+    foldedInto: string;
+    mergedAgentOutputHash: string;
+} | {
+    type: "FOLD_TIMEOUT";
+} | {
+    type: "CANCEL";
+    reason: string;
+} | {
+    type: "ERROR";
+    message: string;
+}, {}, never, never, {
+    type: "gateApproved";
+    params: unknown;
+} | {
+    type: "foldHashMatches";
+    params: unknown;
+}, never, "failed" | "requested" | "gated" | "spawned" | "reported" | "delegated" | "blocked" | "cancelled", string, DelegationRequestInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "delegationRequest";
+    states: {
+        readonly requested: {};
+        readonly gated: {};
+        readonly spawned: {};
+        readonly reported: {};
+        readonly delegated: {};
+        readonly blocked: {};
+        readonly cancelled: {};
+        readonly failed: {};
+    };
+}>;
+export type DelegationRequestMachine = ReturnType<typeof buildRequestMachine>;
+/**
+ * Build the child agent descriptor for a declared delegation spec. Pure.
+ * The orchestrator spawns this via `HostAdapter.spawnAgent` using the model
+ * resolved through `buildChildModelResolutionContext`.
+ */
+export declare function buildChildAgent(parent: DAOAgent, spec: NonNullable<DAOAgent["delegates"]>[number]): DAOAgent;
+/**
+ * Resolve the profile entry for an archetype from a DAO config. Returns
+ * undefined when no profile is registered (the gate then rejects the request).
+ */
+export declare function resolveDelegationProfile(profiles: Partial<Record<string, DelegationProfileEntry>> | undefined, archetype: string): DelegationProfileEntry | undefined;
+export {};
+//# sourceMappingURL=delegation.machine.d.ts.map

package/dist/governance/delegation.machine.d.ts.map

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