@inixiative/foundry-core 0.2.0 → 0.4.0

package/src/capability.ts

@@ -15,7 +15,7 @@
 // a human (or policy hook) approves.
 // ---------------------------------------------------------------------------
 
-import { ActionQueue, type ActionResolution } from "./action-prompt";
+import type { ActionQueue, ActionResolution } from './action-prompt';
 
 // ---------------------------------------------------------------------------
 // Built-in capabilities
@@ -27,34 +27,34 @@ import { ActionQueue, type ActionResolution } from "./action-prompt";
  */
 export type BuiltinCapability =
   // File system
-  | "file:read"
-  | "file:write"
-  | "file:delete"
+  | 'file:read'
+  | 'file:write'
+  | 'file:delete'
   // Network
-  | "net:fetch"
-  | "net:api"
+  | 'net:fetch'
+  | 'net:api'
   // LLM
-  | "llm:call"
-  | "llm:expensive"
+  | 'llm:call'
+  | 'llm:expensive'
   // Data stores
-  | "data:read"
-  | "data:write"
-  | "data:delete"
+  | 'data:read'
+  | 'data:write'
+  | 'data:delete'
   // Execution
-  | "exec:shell"
-  | "exec:process"
+  | 'exec:shell'
+  | 'exec:process'
   // Browser
-  | "browser:navigate"
-  | "browser:interact"
-  | "browser:execute"
-  | "browser:screenshot"
+  | 'browser:navigate'
+  | 'browser:interact'
+  | 'browser:execute'
+  | 'browser:screenshot'
   // Meta
-  | "prompt:auto-resolve";
+  | 'prompt:auto-resolve';
 
 /** Any string is a valid capability. Builtins are just conventions. */
 export type Capability = BuiltinCapability | (string & {});
 
-export type PermissionLevel = "allow" | "prompt" | "deny";
+export type PermissionLevel = 'allow' | 'prompt' | 'deny';
 
 // ---------------------------------------------------------------------------
 // PermissionPolicy
@@ -71,59 +71,42 @@ export interface PermissionPolicy {
   protectedPaths?: string[];
 }
 
-/** Convenience: everything allowed, no prompts. */
-export const UNATTENDED_POLICY: PermissionPolicy = {
-  defaults: "allow",
-  capabilities: {},
-};
-
-/** Convenience: prompt for writes/deletes/exec/expensive, allow reads. */
-export const SUPERVISED_POLICY: PermissionPolicy = {
-  defaults: "prompt",
-  capabilities: {
-    "file:read": "allow",
-    "data:read": "allow",
-    "net:fetch": "allow",
-    "llm:call": "allow",
-  },
-};
-
 /** Convenience: deny dangerous ops, allow reads and cheap LLM. */
 export const RESTRICTED_POLICY: PermissionPolicy = {
-  defaults: "deny",
+  defaults: 'deny',
   capabilities: {
-    "file:read": "allow",
-    "data:read": "allow",
-    "net:fetch": "allow",
-    "llm:call": "allow",
-    "llm:expensive": "deny",
-    "exec:shell": "deny",
-    "exec:process": "deny",
-    "file:delete": "deny",
-    "data:delete": "deny",
-    "browser:navigate": "deny",
-    "browser:interact": "deny",
-    "browser:execute": "deny",
-    "browser:screenshot": "deny",
+    'file:read': 'allow',
+    'data:read': 'allow',
+    'net:fetch': 'allow',
+    'llm:call': 'allow',
+    'llm:expensive': 'deny',
+    'exec:shell': 'deny',
+    'exec:process': 'deny',
+    'file:delete': 'deny',
+    'data:delete': 'deny',
+    'browser:navigate': 'deny',
+    'browser:interact': 'deny',
+    'browser:execute': 'deny',
+    'browser:screenshot': 'deny',
   },
 };
 
 /** Convenience: browser-capable agent — allows navigation and interaction, prompts for JS execution. */
 export const BROWSER_POLICY: PermissionPolicy = {
-  defaults: "prompt",
+  defaults: 'prompt',
   capabilities: {
-    "file:read": "allow",
-    "data:read": "allow",
-    "net:fetch": "allow",
-    "llm:call": "allow",
-    "browser:navigate": "allow",
-    "browser:interact": "allow",
-    "browser:execute": "prompt",
-    "browser:screenshot": "allow",
-    "exec:shell": "deny",
-    "exec:process": "deny",
-    "file:delete": "deny",
-    "data:delete": "deny",
+    'file:read': 'allow',
+    'data:read': 'allow',
+    'net:fetch': 'allow',
+    'llm:call': 'allow',
+    'browser:navigate': 'allow',
+    'browser:interact': 'allow',
+    'browser:execute': 'prompt',
+    'browser:screenshot': 'allow',
+    'exec:shell': 'deny',
+    'exec:process': 'deny',
+    'file:delete': 'deny',
+    'data:delete': 'deny',
   },
 };
 
@@ -136,7 +119,7 @@ export class CapabilityDeniedError extends Error {
   readonly level: PermissionLevel;
   constructor(capability: string, level: PermissionLevel) {
     super(`Capability "${capability}" is ${level}`);
-    this.name = "CapabilityDeniedError";
+    this.name = 'CapabilityDeniedError';
     this.capability = capability;
     this.level = level;
   }
@@ -159,9 +142,11 @@ export class CapabilityGate {
     this._queue = queue;
   }
 
-  get policy(): PermissionPolicy { return this._policy; }
+  get policy(): PermissionPolicy {
+    return this._policy;
+  }
 
-  /** Update policy at runtime (e.g. operator toggles supervised mode). */
+  /** Update policy at runtime. */
   setPolicy(policy: PermissionPolicy): void {
     this._policy = policy;
   }
@@ -173,18 +158,18 @@ export class CapabilityGate {
   async check(capability: Capability, ctx: GateContext): Promise<ActionResolution> {
     const level = this._resolve(capability, ctx);
 
-    if (level === "allow") {
-      return { by: "policy", action: "approved", timestamp: Date.now() };
+    if (level === 'allow') {
+      return { by: 'policy', action: 'approved', timestamp: Date.now() };
     }
 
-    if (level === "deny") {
-      return { by: "policy", action: "rejected", timestamp: Date.now() };
+    if (level === 'deny') {
+      return { by: 'policy', action: 'rejected', timestamp: Date.now() };
     }
 
     // level === "prompt"
     const message = this._buildMessage(capability, ctx);
     return this._queue.prompt({
-      kind: "approval",
+      kind: 'approval',
       message,
       agentId: ctx.agentId,
       threadId: ctx.threadId,
@@ -200,8 +185,8 @@ export class CapabilityGate {
    */
   async require(capability: Capability, ctx: GateContext): Promise<void> {
     const resolution = await this.check(capability, ctx);
-    if (resolution.action !== "approved") {
-      throw new CapabilityDeniedError(capability, "deny");
+    if (resolution.action !== 'approved') {
+      throw new CapabilityDeniedError(capability, 'deny');
     }
   }
 
@@ -221,17 +206,25 @@ export class CapabilityGate {
     if (explicit) return explicit;
 
     // Cost threshold check for LLM calls
-    if (capability === "llm:call" && this._policy.costThreshold != null && ctx?.meta?.estimatedCost != null) {
+    if (
+      capability === 'llm:call' &&
+      this._policy.costThreshold != null &&
+      ctx?.meta?.estimatedCost != null
+    ) {
       if ((ctx.meta.estimatedCost as number) > this._policy.costThreshold) {
-        return "prompt";
+        return 'prompt';
       }
     }
 
     // Protected paths check for file ops
-    if ((capability === "file:write" || capability === "file:delete") && this._policy.protectedPaths?.length && ctx?.meta?.path) {
+    if (
+      (capability === 'file:write' || capability === 'file:delete') &&
+      this._policy.protectedPaths?.length &&
+      ctx?.meta?.path
+    ) {
       const path = ctx.meta.path as string;
       if (this._policy.protectedPaths.some((p) => path.includes(p))) {
-        return "prompt";
+        return 'prompt';
       }
     }
 
@@ -239,14 +232,14 @@ export class CapabilityGate {
   }
 
   private _buildMessage(capability: Capability, ctx: GateContext): string {
-    const detail = ctx.detail ? ` — ${ctx.detail}` : "";
+    const detail = ctx.detail ? ` — ${ctx.detail}` : '';
     return `Agent "${ctx.agentId}" requires capability "${capability}"${detail}`;
   }
 
-  private _urgencyFor(capability: Capability): "low" | "normal" | "high" | "critical" {
-    if (capability === "exec:shell" || capability === "exec:process") return "high";
-    if (capability.endsWith(":delete")) return "high";
-    if (capability === "llm:expensive") return "normal";
-    return "normal";
+  private _urgencyFor(capability: Capability): 'low' | 'normal' | 'high' | 'critical' {
+    if (capability === 'exec:shell' || capability === 'exec:process') return 'high';
+    if (capability.endsWith(':delete')) return 'high';
+    if (capability === 'llm:expensive') return 'normal';
+    return 'normal';
   }
 }

package/src/clarifier.ts

@@ -0,0 +1,46 @@
+import type { AgentConfig } from './base-agent';
+import type { Classification } from './classifier';
+import type { ContextStack } from './context-stack';
+import { Decider, type DeciderConfig, type Decision } from './decider';
+import type { ExecuteMeta } from './executor';
+
+/** The raw message plus the classification already computed upstream. */
+export interface ClarifyPayload {
+  readonly message: string;
+  readonly classification: Classification;
+}
+
+/** needed=true: the request is underspecified and `questions` says what is missing. */
+export interface ClarificationResult {
+  readonly needed: boolean;
+  readonly questions?: string[];
+  readonly reasoning?: string;
+}
+
+export type ClarifyHandler = (
+  context: string,
+  payload: ClarifyPayload,
+  meta?: ExecuteMeta,
+) => Promise<Decision<ClarificationResult>>;
+
+export interface ClarifierConfig extends AgentConfig {
+  handler: ClarifyHandler;
+}
+
+/**
+ * A Clarifier is a Decider that checks whether a request is complete enough
+ * to execute. Its context should hold only a compact completeness schema
+ * (category -> required slots); pair it with a fast model.
+ *
+ * Sits between "route" and "execute". When needed=true the harness
+ * short-circuits and returns the questions instead of dispatching execution.
+ */
+export class Clarifier extends Decider<ClarifyPayload, ClarificationResult> {
+  constructor(config: ClarifierConfig) {
+    super(config as DeciderConfig<ClarifyPayload, ClarificationResult>);
+  }
+
+  override withStack(stack: ContextStack): Clarifier {
+    return new Clarifier({ ...this.agentConfig(stack), handler: this._handler });
+  }
+}

package/src/classifier.ts

@@ -1,7 +1,7 @@
-import { Decider, type DeciderConfig, type Decision } from "./decider";
-import type { AgentConfig } from "./base-agent";
-import type { ContextStack } from "./context-stack";
-import type { ExecuteMeta } from "./executor";
+import type { AgentConfig } from './base-agent';
+import type { ContextStack } from './context-stack';
+import { Decider, type DeciderConfig, type Decision } from './decider';
+import type { ExecuteMeta } from './executor';
 
 /**
  * A classification — "what is this thing?"
@@ -15,7 +15,7 @@ export interface Classification {
 export type ClassifyHandler<TPayload> = (
   context: string,
   payload: TPayload,
-  meta?: ExecuteMeta
+  meta?: ExecuteMeta,
 ) => Promise<Decision<Classification>>;
 
 export interface ClassifierConfig<TPayload = unknown> extends AgentConfig {
@@ -29,10 +29,7 @@ export interface ClassifierConfig<TPayload = unknown> extends AgentConfig {
  * The Classifier has the full taxonomy loaded in its context layers.
  * The caller sends a payload and gets back a category — not the taxonomy.
  */
-export class Classifier<TPayload = unknown> extends Decider<
-  TPayload,
-  Classification
-> {
+export class Classifier<TPayload = unknown> extends Decider<TPayload, Classification> {
   constructor(config: ClassifierConfig<TPayload>) {
     super(config as DeciderConfig<TPayload, Classification>);
   }