@inixiative/foundry-core 0.5.9 → 0.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/foundry-core",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -30,10 +30,10 @@
     "access": "public"
   },
   "engines": {
-    "bun": ">=1.4.2"
+    "bun": ">=1.4.4"
   },
   "peerDependencies": {
-    "@inixiative/archive": "^0.24.0"
+    "@inixiative/archive": "^0.33.0"
   },
   "peerDependenciesMeta": {
     "@inixiative/archive": {
@@ -41,6 +41,6 @@
     }
   },
   "devDependencies": {
-    "@inixiative/archive": "^0.24.0"
+    "@inixiative/archive": "^0.33.1"
   }
 }

package/src/action-prompt.ts

@@ -1,3 +1,9 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:signals
+ */
+import { newId } from './id';
 // ---------------------------------------------------------------------------
 // ActionPrompt — blocking agent→human interaction primitive
 // ---------------------------------------------------------------------------
@@ -30,6 +36,8 @@ export interface ActionResolution {
   readonly by: 'human' | 'policy' | 'timeout';
   readonly action: string; // "approved", "rejected", or an option ID
   readonly input?: string; // for "input" kind prompts
+  /** Context the user typed in the message box and sent with this answer. */
+  readonly note?: string;
   readonly timestamp: number;
 }
 
@@ -129,7 +137,7 @@ export class ActionQueue {
    * Returns the resolution (human choice, policy decision, or timeout).
    */
   async prompt(opts: PromptOpts): Promise<ActionResolution> {
-    const id = `prompt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const id = newId('prompt');
 
     const prompt: ActionPrompt = {
       id,
@@ -197,7 +205,7 @@ export class ActionQueue {
   resolve(
     promptId: string,
     action: string,
-    opts?: { by?: 'human' | 'policy'; input?: string },
+    opts?: { by?: 'human' | 'policy'; input?: string; note?: string },
   ): boolean {
     const prompt = this._prompts.get(promptId);
     if (!prompt || prompt.status !== 'pending') return false;
@@ -206,6 +214,7 @@ export class ActionQueue {
       by: opts?.by ?? 'human',
       action,
       input: opts?.input,
+      ...(opts?.note ? { note: opts.note } : {}),
       timestamp: Date.now(),
     };
 

package/src/adapters/file-memory.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind adapter
+ * @partOf primitive:memory
+ */
 import { existsSync, mkdirSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import {

package/src/adapters/http-memory.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind adapter
+ * @partOf primitive:memory
+ */
 import type { ContextSource } from '../context-layer';
 import type { ContextRef, HydrationAdapter } from '../hydrator';
 import type { Signal } from '../signal';

package/src/adapters/markdown-docs.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind adapter
+ * @partOf primitive:memory
+ */
 import { existsSync, realpathSync } from 'node:fs';
 import { realpath, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
@@ -288,7 +293,13 @@ export function secretInstructionPath(path: string, trusted: readonly string[] =
     name.startsWith('.') ||
     /^id_[a-z0-9]+/i.test(name) ||
     /\.(pem|key|p12|pfx|keystore|jks)$/i.test(name) ||
-    rest.split(sep).some((part) => CREDENTIAL_DIRECTORIES.has(part))
+    rest.split(sep).some((part) => CREDENTIAL_DIRECTORIES.has(part)) ||
+    // A `.private` path is never read (FEAT-005): a segment named or ending `.private`, or holding `.private.`.
+    path
+      .split(sep)
+      .some(
+        (part) => part === '.private' || part.endsWith('.private') || part.includes('.private.'),
+      )
   );
 }
 

package/src/adapters/markdown-hierarchy.ts

@@ -1,6 +1,11 @@
-import { createHash } from 'node:crypto';
+/**
+ * @atlas
+ * @kind adapter
+ * @partOf feature:composition
+ */
 import { readFileSync, realpathSync, statSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { sha256Hex } from '../context-layer';
 import {
   fenceSegments,
   INSTRUCTION_FILE_LIMIT,
@@ -685,7 +690,7 @@ export async function discoverHierarchy(
   return { files, duplicates, refused, probes: [...probes] };
 }
 
-const digest = (text: string) => createHash('sha256').update(text).digest('hex');
+const digest = sha256Hex;
 
 /**
  * Blank lines, trailing whitespace, line endings and runs of spaces inside a line do not make two

package/src/adapters/sqlite-memory.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind adapter
+ * @partOf primitive:memory
+ */
 import { Database } from 'bun:sqlite';
 import type { ContextSource } from '../context-layer';
 import type { ContextRef, HydrationAdapter } from '../hydrator';
@@ -71,7 +76,7 @@ export class SqliteMemory {
 
   /** Read by id. */
   get(id: string): SqliteEntry | undefined {
-    const row = this.db.query('SELECT * FROM entries WHERE id = ?').get(id) as any;
+    const row = this.db.query('SELECT * FROM entries WHERE id = ?').get(id) as SqliteRow | null;
     return row ? this._rowToEntry(row) : undefined;
   }
 
@@ -81,7 +86,7 @@ export class SqliteMemory {
       ? this.db.query('SELECT * FROM entries WHERE kind = ? ORDER BY timestamp DESC')
       : this.db.query('SELECT * FROM entries ORDER BY timestamp DESC');
     const rows = kind ? query.all(kind) : query.all();
-    return (rows as any[]).map(this._rowToEntry);
+    return (rows as SqliteRow[]).map(this._rowToEntry);
   }
 
   /** Full-text search. */
@@ -91,7 +96,7 @@ export class SqliteMemory {
         `SELECT entries.* FROM entries_fts JOIN entries ON entries_fts.id = entries.id WHERE entries_fts MATCH ? ORDER BY rank LIMIT ?`,
       )
       .all(query, limit);
-    return (rows as any[]).map(this._rowToEntry);
+    return (rows as SqliteRow[]).map(this._rowToEntry);
   }
 
   /** Delete by id. */
@@ -105,7 +110,7 @@ export class SqliteMemory {
     const query = kind
       ? this.db.query('SELECT COUNT(*) as c FROM entries WHERE kind = ?')
       : this.db.query('SELECT COUNT(*) as c FROM entries');
-    const row = (kind ? query.get(kind) : query.get()) as any;
+    const row = (kind ? query.get(kind) : query.get()) as { c: number };
     return row.c;
   }
 
@@ -115,7 +120,7 @@ export class SqliteMemory {
       ? this.db.query('SELECT * FROM entries WHERE kind = ? ORDER BY timestamp DESC LIMIT ?')
       : this.db.query('SELECT * FROM entries ORDER BY timestamp DESC LIMIT ?');
     const rows = kind ? query.all(kind, limit) : query.all(limit);
-    return (rows as any[]).map(this._rowToEntry);
+    return (rows as SqliteRow[]).map(this._rowToEntry);
   }
 
   /** Create a ContextSource that loads entries as context. */
@@ -168,7 +173,7 @@ export class SqliteMemory {
     this.db.close();
   }
 
-  private _rowToEntry(row: any): SqliteEntry {
+  private _rowToEntry(row: SqliteRow): SqliteEntry {
     return {
       id: row.id,
       kind: row.kind,
@@ -180,6 +185,16 @@ export class SqliteMemory {
   }
 }
 
+/** A row of the `entries` table as bun:sqlite returns it. */
+interface SqliteRow {
+  id: string;
+  kind: string;
+  content: string;
+  source: string | null;
+  timestamp: number;
+  meta: string | null;
+}
+
 export interface SqliteEntry {
   readonly id: string;
   readonly kind: string;

package/src/base-agent.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind agent
+ * @partOf primitive:agents
+ */
 import { computeHash } from './context-layer';
 import type { AssembledContext, ContextStack, LayerFilter } from './context-stack';
 import type { TokenCounts } from './token-counts';

package/src/bounded-set.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind utils
+ * @partOf primitive:signals
+ */
 /**
  * A set with bounded capacity that evicts oldest entries when full.
  * Used for message deduplication at harness ingress.

package/src/cache-lifecycle.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:contextLayers
+ */
 import type { ContextLayer, LayerState } from './context-layer';
 import type { ContextStack } from './context-stack';
 

package/src/capability.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind helper
+ * @partOf primitive:agents, primitive:tools
+ */
 // ---------------------------------------------------------------------------
 // Capability — permission flags and gating for dangerous operations
 // ---------------------------------------------------------------------------

package/src/clarifier.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind agent
+ * @partOf primitive:agents
+ */
 import type { AgentConfig } from './base-agent';
 import type { Classification } from './classifier';
 import type { ContextStack } from './context-stack';

package/src/classifier.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind agent
+ * @partOf primitive:agents
+ */
 import type { AgentConfig } from './base-agent';
 import type { ContextStack } from './context-stack';
 import { Decider, type DeciderConfig, type Decision } from './decider';

package/src/context-layer.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:contextLayers
+ */
 import type { OwnershipScope } from './scope';
 
 /**
@@ -354,6 +359,11 @@ export function computeHash(content: string): string {
   return Bun.hash(content).toString(16).slice(0, 16);
 }
 
+/** SHA-256 as hex: for content addresses and digests that are persisted or compared across processes (computeHash is a fast in-memory cache key, not this). */
+export function sha256Hex(content: string | Uint8Array): string {
+  return new Bun.CryptoHasher('sha256').update(content).digest('hex');
+}
+
 export class ContextLayer {
   readonly id: string;
   readonly owner?: OwnershipScope;

package/src/context-stack.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:contextLayers
+ */
 import { type ContextLayer, computeHash, type LayerState } from './context-layer';
 import type { OwnershipScope } from './scope';
 

package/src/credentials.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind helper
+ * @partOf primitive:secrets
+ */
 /** Credential references belong in configuration; secrets stay behind the resolver. */
 /** `kingdom-signet` names the Signet a paired Kingdom granted, by the destination's origin plus the owner it was paired as. */
 export type CredentialReference =

package/src/decider.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind agent
+ * @partOf primitive:agents
+ */
 import { type AgentConfig, BaseAgent, type ExecutionResult } from './base-agent';
 import { computeHash } from './context-layer';
 import type { ContextStack, LayerFilter } from './context-stack';

package/src/delivery-evidence.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind helper
+ * @partOf primitive:nativeSessions
+ */
 /** Portable SHA-256 for public evidence, shared by Bun and the historical browser.
  * This is an integrity join, not a signature or native delivery acknowledgment. */
 export function evidenceDigest(text: string): string {

package/src/event-stream.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:signals
+ */
 import type { ActionPrompt } from './action-prompt';
 import type { LifecycleEvent } from './cache-lifecycle';
 import type { DispatchContext } from './middleware';

package/src/executor.ts

@@ -1,6 +1,11 @@
+/**
+ * @atlas
+ * @kind agent
+ * @partOf primitive:agents
+ */
 import { type AgentConfig, BaseAgent, type ExecutionResult } from './base-agent';
 import { computeHash, REQUIRED_CONTEXT_BLOCKED } from './context-layer';
-import type { AssembledContext, ContextStack, LayerFilter } from './context-stack';
+import type { AssembledContext, ContextStack, LayerFilter, PromptBlock } from './context-stack';
 import { buildInjectionArtifact, type InjectionArtifact, type MessageDecoration } from './messages';
 import type { NativeEvidence, NativeObservation } from './native-evidence';
 import {
@@ -52,6 +57,16 @@ export interface ExecuteMeta {
   images?: readonly ImageInput[];
 }
 
+/**
+ * The user's message as a turn sends it: the after-message notes (Wardens chiming in) appended to
+ * its end below a rule, each note's text in order. No notes: the message as typed.
+ */
+export function withAfterMessageNotes(message: string, notes: readonly PromptBlock[]): string {
+  return notes.length
+    ? `${message}\n\n---\n\n${notes.map((note) => note.text).join('\n\n')}`
+    : message;
+}
+
 export type ExecuteHandler<TPayload, TResult> = (
   context: string,
   payload: TPayload,
@@ -214,9 +229,7 @@ export class Executor<TPayload = unknown, TResult = unknown> extends BaseAgent<T
     let recording = true;
     try {
       const sent = (
-        notes.length && typeof payload === 'string'
-          ? `${payload}\n\n---\n\n${notes.map((note) => note.text).join('\n\n')}`
-          : payload
+        typeof payload === 'string' ? withAfterMessageNotes(payload, notes) : payload
       ) as TPayload;
       output = await this._handler(context, sent, {
         ...meta,

package/src/feedback/archive-turns.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind transformer
+ * @partOf feature:feedback, integration:archive
+ */
 import type { ArchiveSnapshot } from '@inixiative/archive';
 import { typedPrompt } from '@inixiative/archive/import';
 import type { TranscriptTurn } from './correction';

package/src/feedback/correction.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf feature:feedback
+ */
 import { createHash } from 'node:crypto';
 
 // The Prospector's correction detection (moved from Oracle's session miner), shared by Oracle's
@@ -216,8 +221,12 @@ export function extractCorrections(
   return { corrections, secretsScrubbed };
 }
 
-const SECRET_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
-  [/sk-ant-[A-Za-z0-9_-]{8,}/g, '[REDACTED:anthropic-key]'],
+/**
+ * Credentials by their own shape (a provider's token prefix, a key block): specific enough that a
+ * match is a secret. Foundry lifts these from a message even when the person forgot `$$` (FEAT-005).
+ */
+const SHAPED_SECRETS: ReadonlyArray<readonly [RegExp, string]> = [
+  [/sk-ant-[A-Za-z0-9_-]{20,}/g, '[REDACTED:anthropic-key]'],
   [/sk-[A-Za-z0-9_-]{20,}/g, '[REDACTED:api-key]'],
   [/gh[pousr]_[A-Za-z0-9]{20,}/g, '[REDACTED:github-token]'],
   [/github_pat_[A-Za-z0-9_]{20,}/g, '[REDACTED:github-token]'],
@@ -231,8 +240,19 @@ const SECRET_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
   [/eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, '[REDACTED:jwt]'],
   [/\b[a-z]+_(?:live|test|prod|runtime)_[A-Za-z0-9]{16,}/g, '[REDACTED:token]'],
   [/\b(?:npm_|glpat-|hf_)[A-Za-z0-9_-]{20,}/g, '[REDACTED:token]'],
+  // Kingdom's run, refresh and Signet access tokens: the prefix and exactly 43 base64url characters.
+  [/\bkingdom_(?:run_|refresh_)?[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-])/g, '[REDACTED:kingdom-token]'],
+  // API tokens Kingdom, template and Tribe issue: `<environment>_<owner model>_<48 hex>`.
+  [
+    /\b(?:local|pr|staging|prod|test)_(?:user|org|orgUser|space|spaceUser|integration)_[0-9a-f]{48}\b/g,
+    '[REDACTED:api-token]',
+  ],
   [/hooks\.slack\.com\/services\/[A-Za-z0-9/]+/g, '[REDACTED:slack-webhook]'],
   [/\bASIA[A-Z0-9]{16}/g, '[REDACTED:aws-key]'],
+];
+
+/** Credentials by context (an assignment, a header, a URL): a match may be a secret, so it is scrubbed but never lifted. */
+const CONTEXT_SECRETS: ReadonlyArray<readonly [RegExp, string]> = [
   [/\b(Bearer|Basic|DPoP)\s+[A-Za-z0-9._~+/=-]{16,}/g, '$1 [REDACTED:credential]'],
   [/\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)[^\s@/]+@/gi, '$1[REDACTED:password]@'],
   [
@@ -245,6 +265,32 @@ const SECRET_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
   ],
 ];
 
+const SECRET_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+  ...SHAPED_SECRETS,
+  ...CONTEXT_SECRETS,
+];
+
+/**
+ * The shaped credentials safe to lift from a message the person forgot to mark: each never starts
+ * inside a word (`task-runner-…` holds `sk-…`), and the two loosest shapes (`sk-…` and
+ * `<word>_live_<…>`, which long hyphenated or snake_case names also fit) must carry a digit. Fresh
+ * regex objects, so lifting never shares match state with `scrubSecrets`. Scrubbing a false match is
+ * harmless; lifting one would take words out of the person's message.
+ */
+export const SHAPED_SECRET_PATTERNS: readonly RegExp[] = SHAPED_SECRETS.map(([pattern]) => {
+  const loose =
+    pattern.source.startsWith('sk-[') || pattern.source.includes('(?:live|test|prod|runtime)');
+  const digit = loose ? '(?=[A-Za-z0-9_-]*\\d)' : '';
+  return new RegExp(`(?<![A-Za-z0-9_-])${digit}(?:${pattern.source})`, pattern.flags);
+});
+
+/** How many credentials known only by context (`PASSWORD=…`, `Bearer …`, a URL password) the text holds. */
+export function contextSecretHits(text: string): number {
+  let hits = 0;
+  for (const [pattern] of CONTEXT_SECRETS) hits += [...text.matchAll(pattern)].length;
+  return hits;
+}
+
 /** Replace credential-shaped substrings. Transcripts are exactly where leaked keys live. */
 export function scrubSecrets(text: string): { text: string; hits: number } {
   let hits = 0;

package/src/feedback/experiment-gate.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind helper
+ * @partOf feature:evals
+ */
 /**
  * The experiment gate (`.claude/skills/experiment/SKILL.md`), shared by Foundry's eval scripts and
  * Oracle's replay runner: a wide run (more than TINY_MOMENTS moments, or whatever else the caller

package/src/feedback/review-findings.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf feature:feedback
+ */
 import {
   type Authorship,
   CONCEPT_CLUSTERS,

package/src/feedback/warden-labels.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind type
+ * @partOf feature:evals
+ */
 import type { WardenProbe } from './warden-probes';
 
 /** One Warden of the roster as the labeler sees it. */

package/src/feedback/warden-prefilter.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf feature:wardens
+ */
 // The Warden pre-filter: one cheap local yes/no per Warden before it is asked. Data and pure
 // functions only, so Oracle scores runs the same way; Foundry's provider makes the call. It fails
 // open: a Warden is skipped only on a confident no, and anything else (an unsure score, an error, no

package/src/feedback/warden-probes.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf feature:evals
+ */
 // Warden probes: the offline measurement of how well a Warden charter keeps the chorus quiet, in
 // scope and right. Data and pure functions only, so Oracle can score runs on a core-only dependency;
 // callers bring the probes, the Warden calls and the judge call.

package/src/harness.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:agents
+ */
 import type { ExecutionResult } from './base-agent';
 import { BoundedSet } from './bounded-set';
 import type { ClarificationResult, ClarifyPayload } from './clarifier';
@@ -512,7 +517,7 @@ export class Harness {
         const layerFilter = this.buildLayerFilter(undefined, undefined, requestedLayers);
         const settled = await Promise.allSettled(
           decisionStages.map(async (stage) => {
-            const span = trace.startDetached(`${stage.role}:${stage.agentId}`, stage.role as any, {
+            const span = trace.startDetached(`${stage.role}:${stage.agentId}`, stage.role, {
               agentId: stage.agentId,
               threadId: this.thread.id,
               input: message.payload,
@@ -638,7 +643,7 @@ export class Harness {
         }
 
         // Trace and dispatch (foreground — blocks pipeline)
-        const stageSpan = trace.start(`${stage.role}:${agentId}`, stage.role as any, {
+        const stageSpan = trace.start(`${stage.role}:${agentId}`, stage.role, {
           agentId,
           threadId: this.thread.id,
           input: message.payload,

package/src/hydrator.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:contextLayers
+ */
 import type { ContextSource } from './context-layer';
 
 /**

package/src/id.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind utils
+ * @partOf primitive:thread
+ */
 import { uuidv7 } from 'uuidv7';
 
 /**