@tangle-network/agent-runtime 0.89.0 → 0.90.0

package/dist/mcp/index.js

@@ -1,3 +1,6 @@
+import {
+  coderTaskToPrompt
+} from "../chunk-5IBQAPVB.js";
 import {
   createPropagatingTraceEmitter,
   readTraceContextFromEnv,
@@ -6,7 +9,7 @@ import {
 import {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "../chunk-5AVV7KAH.js";
+} from "../chunk-XQEISTK2.js";
 import {
   createKbGate
 } from "../chunk-SGKPNBXE.js";
@@ -14,7 +17,7 @@ import {
   assertTraceDerivedFindings,
   runCoderChecks,
   selectValidWinner
-} from "../chunk-PIPPLSOF.js";
+} from "../chunk-4IBAMGBE.js";
 import {
   DELEGATE_DESCRIPTION,
   DELEGATE_FEEDBACK_DESCRIPTION,
@@ -64,7 +67,8 @@ import {
   validateDelegateUiAuditArgs,
   validateDelegationHistoryArgs,
   validateDelegationStatusArgs
-} from "../chunk-N7EJV7N3.js";
+} from "../chunk-QSNSMJSZ.js";
+import "../chunk-DPEUKJRO.js";
 import "../chunk-UD4BHQMI.js";
 import {
   deleteBoxSafe,
@@ -79,10 +83,6 @@ import {
 import {
   ValidationError
 } from "../chunk-YEJR7IXO.js";
-import {
-  coderTaskToPrompt
-} from "../chunk-5IBQAPVB.js";
-import "../chunk-DPEUKJRO.js";
 import "../chunk-DGUM43GV.js";
 
 // src/mcp/executor.ts

package/dist/{openai-tools-BnrOmGjN.d.ts → openai-tools-D0xmzo0y.d.ts}

@@ -1,4 +1,4 @@
-import { O as OpenAIChatTool } from './types-ESeMOj94.js';
+import { O as OpenAIChatTool } from './types-Dnk189QA.js';
 
 /**
  *

package/dist/profiles.d.ts

@@ -1,8 +1,8 @@
 import { a as UiFinding, U as UiLens } from './substrate-DO2GHNg2.js';
 export { C as CoderTask, b as UI_FINDING_SEVERITIES, c as UI_LENSES, d as UiFindingScreenshot, e as UiFindingSeverity, f as coderTaskToPrompt } from './substrate-DO2GHNg2.js';
-import { S as SandboxClient, b as OutputAdapter, V as Validator, A as AgentRunSpec } from './types-ESeMOj94.js';
-import { SandboxEvent } from '@tangle-network/sandbox';
-import { AgentProfile } from '@tangle-network/agent-interface';
+import { AgentProfile, SandboxEvent } from '@tangle-network/sandbox';
+import { V as Validator, A as AgentRunSpec, b as OutputAdapter, D as Driver, S as SandboxClient } from './types-Dnk189QA.js';
+import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
 import '@tangle-network/agent-eval';
 
 /**
@@ -96,6 +96,197 @@ declare function summarizeRegistry(reg: AuditRegistry): AuditIndex;
  */
 declare function writeAuditIndex(workspaceDir: string): Promise<string>;
 
+/**
+ * Opinionated preset for source-grounded research
+ * tasks. The agent is told to:
+ *   - bound its work to a single `knowledgeNamespace`
+ *   - emit `items[]` carrying provenance + confidence
+ *   - emit `citations[]` linking quotes back to source urls
+ *   - emit `proposedWrites[]` — never call materialize itself
+ *   - describe `gaps` it could not answer
+ *
+ * The profile is stateless and agent-agnostic. `harness` selects the
+ * sandbox-SDK backend. For heterogeneous fanout, use
+ * `multiHarnessResearcherFanout`.
+ *
+ * Propose-don't-apply: the profile NEVER writes to the knowledge base.
+ * It produces `proposedWrites: KnowledgeUpdate[]` in the output. The
+ * caller (gtm-agent, journey-eval, user) decides whether to feed those
+ * updates through `applyKnowledgeWriteBlocks` / a KbStore put.
+ *
+ * Namespace isolation: every `KnowledgeItem` + `KnowledgeUpdate` in the
+ * output carries `namespace`. The validator hard-fails when any item
+ * touches a namespace other than `task.knowledgeNamespace`.
+ *
+ * @experimental
+ */
+
+/** Source families a researcher profile may prefer for a task. @experimental */
+type ResearchSource = 'web' | 'corpus' | 'twitter' | 'github' | 'docs';
+/** Task contract for a source-grounded research agent. @experimental */
+interface ResearchTask {
+    /** The research question to answer. */
+    question: string;
+    /** Bound: e.g. "audience for cpg-founder ICP". */
+    scope?: string;
+    /** Multi-tenant scope (customer-id, workspace-id). Validator enforces. */
+    knowledgeNamespace: string;
+    sources?: ResearchSource[];
+    recencyWindow?: {
+        since?: Date;
+        until?: Date;
+    };
+    maxItems?: number;
+    /** Per-item minimum confidence in [0, 1]. Validator scores recall vs this. */
+    minConfidence?: number;
+}
+/**
+ * Knowledge item emitted by the researcher.
+ *
+ * Profile-local type. When agent-knowledge promotes `KnowledgeClaim` →
+ * top-level `KnowledgeItem` substrate-wide, these fields collapse 1:1.
+ *
+ * @experimental
+ */
+interface KnowledgeItem {
+    id: string;
+    /** Multi-tenant scope. MUST equal `task.knowledgeNamespace`. */
+    namespace: string;
+    /** The factual claim, in the researcher's words. */
+    claim: string;
+    /** Provenance — at least one entry required. */
+    evidence: Array<{
+        source: string;
+        quote?: string;
+        url?: string;
+        capturedAt: number;
+    }>;
+    /** Researcher's self-reported confidence in [0, 1]. */
+    confidence: number;
+    /** Prior item ids this supersedes (chain). */
+    supersedes?: string[];
+    /** Set if the agent is retracting an earlier item. Unix ms. */
+    retractedAt?: number;
+    authoredBy: {
+        kind: 'human' | 'agent';
+        id: string;
+    };
+}
+/**
+ * A proposed write to the knowledge base. The profile does NOT apply
+ * these — the caller decides.
+ *
+ * @experimental
+ */
+type KnowledgeUpdate = {
+    kind: 'insert';
+    namespace: string;
+    item: KnowledgeItem;
+} | {
+    kind: 'supersede';
+    namespace: string;
+    previousId: string;
+    item: KnowledgeItem;
+} | {
+    kind: 'retract';
+    namespace: string;
+    itemId: string;
+    reason: string;
+};
+/**
+ * Researcher output. Required fields are typed; optional fields preserve
+ * the agent's free-form intelligence (`notes`, `raw`). The validator
+ * enforces the typed minimum.
+ *
+ * @experimental
+ */
+interface ResearchOutput {
+    items: KnowledgeItem[];
+    citations: Array<{
+        url: string;
+        quote: string;
+        confidence: number;
+    }>;
+    proposedWrites: KnowledgeUpdate[];
+    gaps?: string[];
+    notes?: string;
+    /** Anything the agent emitted beyond the typed fields. */
+    raw?: unknown;
+}
+/** Options for the source-grounded researcher profile preset. @experimental */
+interface ResearcherProfileOptions {
+    /** Sandbox-SDK backend.type. Default `'opencode/zai-coding-plan/glm-5.1'`. */
+    harness?: string;
+    /** Default model id passed in `AgentProfile.model.default`. */
+    model?: string;
+    /** Custom system prompt replacement. Default = built-in researcher preset. */
+    systemPrompt?: string;
+    /** Stable name for `AgentRunSpec.name`. Default = `researcher-${harness}`. */
+    name?: string;
+    /**
+     * Default 0.7. Minimum (citations with quote) / items ratio for `valid=true`.
+     * Below this floor, citation_density scores < 1 and the item set is gated.
+     */
+    citationDensityMin?: number;
+}
+/** Build a source-grounded researcher profile with output parsing and validation. @experimental */
+declare function researcherProfile(options?: ResearcherProfileOptions & {
+    task?: ResearchTask;
+}): {
+    profile: AgentProfile;
+    taskToPrompt: (task: ResearchTask) => string;
+    output: OutputAdapter<ResearchOutput>;
+    validator: Validator<ResearchOutput>;
+    agentRunSpec: AgentRunSpec<ResearchTask>;
+};
+/** @experimental */
+interface MultiHarnessResearcherFanoutOptions {
+    /** Backend.type identifiers, one per parallel agent. */
+    harnesses?: string[];
+    /** Optional per-harness model override. Indexed parallel to `harnesses`. */
+    models?: (string | undefined)[];
+    /** Default citation density floor for the shared validator. */
+    citationDensityMin?: number;
+    /** Optional task — narrows the validator's namespace check. */
+    task?: ResearchTask;
+}
+/**
+ * Build a fanout topology over multiple harnesses. The kernel round-robins
+ * `agentRuns` across the N parallel iterations and the `FanoutVote` driver
+ * picks the highest-scoring valid output.
+ *
+ * @experimental
+ */
+declare function multiHarnessResearcherFanout(options?: MultiHarnessResearcherFanoutOptions): {
+    agentRuns: AgentRunSpec<ResearchTask>[];
+    output: OutputAdapter<ResearchOutput>;
+    validator: Validator<ResearchOutput>;
+    driver: Driver<ResearchTask, ResearchOutput, 'done'>;
+};
+/**
+ * Build a validator that closes over a specific `ResearchTask`'s constraints.
+ *
+ * Checks in order:
+ *   1. Items must be non-empty.
+ *   2. Every item carries `evidence.length >= 1`.
+ *   3. Every item + proposedWrite is scoped to `task.knowledgeNamespace`
+ *      (hard-fail on any namespace mismatch — defence in depth for the
+ *      multi-tenant invariant).
+ *   4. Citation density (citations with quote / items) >= floor.
+ *
+ * Aggregate score:
+ *   0.4 · citation_density
+ * + 0.2 · source_diversity (distinct sources / max(items, 1))
+ * + 0.2 · recency_match (mean fraction within `recencyWindow`)
+ * + 0.2 · (1 − gaps/maxGaps), maxGaps = max(items, 1)
+ *
+ * @experimental
+ */
+declare function createResearcherValidator(task: ResearchTask, config?: {
+    citationDensityMin?: number;
+    namespaceCheck?: boolean;
+}): Validator<ResearchOutput>;
+
 /**
  *
  * UI auditor task + output shapes — what one iteration of the audit loop
@@ -440,7 +631,7 @@ interface UiAuditorProfileOptions {
  * @experimental
  */
 declare function uiAuditorProfile(options?: UiAuditorProfileOptions): {
-    profile: AgentProfile;
+    profile: AgentProfile$1;
     taskToPrompt: (task: UiAuditTask) => string;
     output: OutputAdapter<UiAuditOutput>;
     validator: Validator<UiAuditOutput>;
@@ -511,4 +702,4 @@ declare function formatAuditorPrompt(task: UiAuditTask): string;
 /** Build a `Validator` that rejects off-lens findings and findings missing screenshot evidence. @experimental */
 declare function createUiAuditorValidator(task: UiAuditTask): Validator<UiAuditOutput>;
 
-export { type AppendFindingsResult, type AuditIndex, type AuditRegistry, type AuditRegistryCapture, type BrowserContextHandle, type BrowserHandle, type InProcessUiAuditClientOptions, LENS_BRIEFS, type PageHandle, type RegisterCapturesOptions, SHARED_AUDITOR_RULES, type UiAuditCapture, type UiAuditCaptureRequest, type UiAuditOutput, type UiAuditTask, type UiAuditViewport, type UiAuditorProfileOptions, UiFinding, type UiJudge, type UiJudgeInput, type UiJudgeOutput, type UiJudgeTokenUsage, UiLens, appendFindings, buildAuditorSystemPrompt, createInProcessUiAuditClient, createUiAuditorValidator, decodeAuditTaskEnvelope, encodeAuditTaskEnvelope, formatAuditorPrompt, initAuditWorkspace, parseAuditorEvents, readAuditRegistry, registerCaptures, summarizeRegistry, uiAuditorProfile, writeAuditIndex };
+export { type AppendFindingsResult, type AuditIndex, type AuditRegistry, type AuditRegistryCapture, type BrowserContextHandle, type BrowserHandle, type InProcessUiAuditClientOptions, type KnowledgeItem, type KnowledgeUpdate, LENS_BRIEFS, type MultiHarnessResearcherFanoutOptions, type PageHandle, type RegisterCapturesOptions, type ResearchOutput, type ResearchSource, type ResearchTask, type ResearcherProfileOptions, SHARED_AUDITOR_RULES, type UiAuditCapture, type UiAuditCaptureRequest, type UiAuditOutput, type UiAuditTask, type UiAuditViewport, type UiAuditorProfileOptions, UiFinding, type UiJudge, type UiJudgeInput, type UiJudgeOutput, type UiJudgeTokenUsage, UiLens, appendFindings, buildAuditorSystemPrompt, createInProcessUiAuditClient, createResearcherValidator, createUiAuditorValidator, decodeAuditTaskEnvelope, encodeAuditTaskEnvelope, formatAuditorPrompt, initAuditWorkspace, multiHarnessResearcherFanout, parseAuditorEvents, readAuditRegistry, registerCaptures, researcherProfile, summarizeRegistry, uiAuditorProfile, writeAuditIndex };

package/dist/profiles.js

@@ -1,6 +1,11 @@
 import {
   coderTaskToPrompt
 } from "./chunk-5IBQAPVB.js";
+import {
+  createResearcherValidator,
+  multiHarnessResearcherFanout,
+  researcherProfile
+} from "./chunk-5QOB7H74.js";
 import {
   UI_FINDING_SEVERITIES,
   UI_LENSES
@@ -851,14 +856,17 @@ export {
   buildAuditorSystemPrompt,
   coderTaskToPrompt,
   createInProcessUiAuditClient,
+  createResearcherValidator,
   createUiAuditorValidator,
   decodeAuditTaskEnvelope,
   encodeAuditTaskEnvelope,
   formatAuditorPrompt,
   initAuditWorkspace,
+  multiHarnessResearcherFanout,
   parseAuditorEvents,
   readAuditRegistry,
   registerCaptures,
+  researcherProfile,
   summarizeRegistry,
   uiAuditorProfile,
   writeAuditIndex