@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.10

package/packages/agentsam-hooks/test/runtime.test.mjs

@@ -0,0 +1,258 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  HOOK_PROTOCOL_SCHEMA,
+  AgentSamHooks,
+  HookPermissionError,
+  createCallbackHookAdapter,
+  createCommandHookAdapter,
+  createHookRuntime,
+  createHookedCapabilityAdapter,
+  createHookedProviderAdapter,
+  createHttpHookAdapter,
+  normalizeHookEvent,
+  normalizeHookOutput,
+} from '../src/index.js';
+
+const cwd = process.cwd();
+
+test('contract accepts ergonomic event/output aliases but emits canonical fields', () => {
+  assert.equal(HOOK_PROTOCOL_SCHEMA, 'agentsam.hook.v1');
+  assert.equal(new AgentSamHooks().list().length, 0);
+  assert.equal(normalizeHookEvent('onPreToolUse'), 'pre_tool_use');
+  assert.deepEqual(normalizeHookOutput('session_start', { modifiedConfig: { auto_compact: false } }), { modified_config: { auto_compact: false } });
+  assert.deepEqual(normalizeHookOutput('pre_tool_use', {
+    permissionDecision: 'allow',
+    modifiedArgs: { timeout: 30 },
+    additionalContext: 'bounded context',
+  }), {
+    permission_decision: 'allow',
+    modified_args: { timeout: 30 },
+    additional_context: 'bounded context',
+  });
+  assert.throws(() => normalizeHookOutput('post_tool_use', { permission_decision: 'deny' }), /not_supported/);
+  assert.throws(() => normalizeHookOutput('pre_tool_use', { permissionDecison: 'allow' }), /unsupported_hook_output_field/);
+});
+
+test('runtime composes modifications in priority order and receipts exclude values', async () => {
+  const observed = [];
+  const hooks = createHookRuntime({
+    onReceipt: (receipt) => observed.push(receipt),
+    hooks: {
+      pre_tool_use: [
+        {
+          id: 'second', priority: 20,
+          handler: ({ input }) => ({
+            permission_decision: 'allow',
+            modified_args: { ...input.tool_args, second: true },
+            additional_context: 'second context',
+          }),
+        },
+        {
+          id: 'first', priority: 10,
+          handler: ({ input }) => ({
+            permission_decision: 'allow',
+            modified_args: { ...input.tool_args, secret: 'not-in-receipt' },
+            additional_context: 'first context',
+          }),
+        },
+      ],
+    },
+  });
+  const result = await hooks.dispatch('pre_tool_use', {
+    tool_name: 'example.read', tool_args: { value: 1 },
+  }, { session_id: 'session-test' }, { cwd });
+  assert.deepEqual(result.input.tool_args, { value: 1, secret: 'not-in-receipt', second: true });
+  assert.equal(result.output.additional_context, 'first context\n\nsecond context');
+  assert.deepEqual(result.receipts.map((row) => row.hook_id), ['first', 'second']);
+  assert.equal(JSON.stringify(observed).includes('not-in-receipt'), false);
+});
+
+test('session-start config patches compose without discarding prior or base keys', async () => {
+  const hooks = createHookRuntime({ hooks: {
+    session_start: [
+      { id: 'model', priority: 10, handler: () => ({ modified_config: { model_key: 'xai:grok-4' } }) },
+      { id: 'effort', priority: 20, handler: () => ({ modified_config: { reasoning_effort: 'high' } }) },
+    ],
+  } });
+  const result = await hooks.dispatch('session_start', { config: { auto_compact: true } });
+  assert.deepEqual(result.input.config, {
+    auto_compact: true,
+    model_key: 'xai:grok-4',
+    reasoning_effort: 'high',
+  });
+  assert.deepEqual(result.output.modified_config, {
+    model_key: 'xai:grok-4',
+    reasoning_effort: 'high',
+  });
+});
+
+test('pre hooks fail closed by default while observers fail open', async () => {
+  const pre = createHookRuntime({ hooks: { pre_tool_use: { id: 'policy', handler: () => { throw new Error('offline api_key=do-not-record'); } } } });
+  const denied = await pre.dispatch('pre_tool_use', { tool_name: 'x', tool_args: {} });
+  assert.equal(denied.output.permission_decision, 'deny');
+  assert.match(denied.output.permission_decision_reason, /failed closed/);
+  assert.doesNotMatch(JSON.stringify(denied), /do-not-record/);
+  assert.deepEqual({
+    code: denied.receipts[0].error.error_code,
+    reason: denied.receipts[0].error.reason,
+    domain: denied.receipts[0].error.domain,
+    behavior: denied.receipts[0].error.failure_behavior,
+    sideEffect: denied.receipts[0].error.side_effect_state,
+    retryable: denied.receipts[0].error.retryable,
+  }, {
+    code: 'INTERNAL', reason: 'hook_handler_failed', domain: 'hook', behavior: 'fail_closed',
+    sideEffect: 'not_started', retryable: false,
+  });
+  assert.match(denied.receipts[0].error.fingerprint, /^err_[a-f0-9]{16}$/);
+  assert.equal(denied.receipts[0].native_evidence.message.includes('do-not-record'), false);
+
+  const post = createHookRuntime({ hooks: { post_tool_use: { id: 'audit', handler: () => { throw new Error('hook_http_timeout:1000'); } } } });
+  const allowed = await post.dispatch('post_tool_use', { tool_name: 'x', tool_result: { ok: true } });
+  assert.deepEqual(allowed.input.tool_result, { ok: true });
+  assert.equal(allowed.errors.length, 1);
+  assert.equal(allowed.receipts[0].error.reason, 'hook_http_timeout');
+  assert.equal(allowed.receipts[0].error.error_code, 'DEADLINE_EXCEEDED');
+  assert.equal(allowed.receipts[0].error.failure_behavior, 'fail_open');
+  assert.equal(allowed.receipts[0].error.side_effect_state, 'confirmed_applied');
+  assert.equal(allowed.receipts[0].error.retryable, false);
+});
+
+test('callback adapter exposes input and invocation without changing wire envelope', async () => {
+  const handler = createCallbackHookAdapter((input, invocation, envelope) => ({
+    permission_decision: input.tool_name === 'read' ? 'allow' : 'deny',
+    metadata: { session: invocation.session_id, schema: envelope.schema },
+  }));
+  const hooks = createHookRuntime({ hooks: { pre_tool_use: handler } });
+  const result = await hooks.dispatch('pre_tool_use', { tool_name: 'read', tool_args: {} }, { session_id: 's1' });
+  assert.equal(result.output.permission_decision, 'allow');
+  assert.deepEqual(result.output.metadata, { session: 's1', schema: 'agentsam.hook.v1' });
+});
+
+test('command adapter uses JSON stdin/stdout without a shell', async () => {
+  const script = [
+    "let data='';",
+    "process.stdin.on('data', c => data += c);",
+    "process.stdin.on('end', () => { const row=JSON.parse(data); console.error('diagnostic'); console.log(JSON.stringify({permission_decision: row.input.tool_name === 'safe' ? 'allow' : 'deny'})); });",
+  ].join('');
+  const adapter = createCommandHookAdapter({ command: process.execPath, args: ['-e', script], cwd, timeout_ms: 2_000 });
+  const hooks = createHookRuntime({ hooks: { pre_tool_use: { id: 'external', handler: adapter } } });
+  const result = await hooks.dispatch('pre_tool_use', { tool_name: 'safe', tool_args: {} }, {}, { cwd });
+  assert.equal(result.output.permission_decision, 'allow');
+});
+
+test('HTTP adapter exchanges the canonical envelope with a portable service', async (t) => {
+  const server = http.createServer((request, response) => {
+    let body = '';
+    request.on('data', chunk => { body += chunk; });
+    request.on('end', () => {
+      const envelope = JSON.parse(body);
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify({
+        permission_decision: envelope.schema === 'agentsam.hook.v1' ? 'allow' : 'deny',
+      }));
+    });
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => server.close());
+  const address = server.address();
+  const handler = createHttpHookAdapter({ url: `http://127.0.0.1:${address.port}/hook`, timeout_ms: 2_000 });
+  const hooks = createHookRuntime({ hooks: { pre_tool_use: handler } });
+  const result = await hooks.dispatch('pre_tool_use', { tool_name: 'read', tool_args: {} });
+  assert.equal(result.output.permission_decision, 'allow');
+});
+
+test('capability wrapper enforces ask, argument modification, post transformation, and bounded retry', async () => {
+  let attempts = 0;
+  const hooks = createHookRuntime({ hooks: {
+    pre_tool_use: ({ input }) => ({
+      permission_decision: 'ask',
+      modified_args: { ...input.tool_args, approved: true },
+    }),
+    post_tool_use: ({ input }) => ({ modified_result: { ...input.tool_result, transformed: true } }),
+    error_occurred: ({ input }) => input.error_context === 'tool_execution'
+      ? { error_handling: 'retry', retry_count: 1 }
+      : null,
+  } });
+  const base = {
+    toolDescriptors: () => [{ name: 'example.write', input_schema: { type: 'object' } }],
+    async invoke(_id, input) {
+      attempts += 1;
+      if (attempts === 1) throw new Error('temporary');
+      return { input };
+    },
+  };
+  const adapter = createHookedCapabilityAdapter(base, {
+    hookRuntime: hooks,
+    requestPermission: async () => true,
+    maxRetries: 1,
+  });
+  const result = await adapter.invoke('example.write', { value: 1 });
+  assert.equal(attempts, 2);
+  assert.deepEqual(result, { input: { value: 1, approved: true }, transformed: true });
+
+  const noApproval = createHookedCapabilityAdapter(base, { hookRuntime: hooks, requestPermission: async () => false });
+  await assert.rejects(noApproval.invoke('example.write', {}), HookPermissionError);
+});
+
+test('provider wrapper modifies a provider-neutral request and result', async () => {
+  const hooks = createHookRuntime({ hooks: {
+    pre_model_use: ({ input }) => ({
+      permission_decision: 'allow',
+      modified_request: { ...input.request, model: 'portable-model', temperature: 0 },
+    }),
+    post_model_use: ({ input }) => ({ modified_result: { ...input.model_result, output_text: 'redacted' } }),
+  } });
+  let request;
+  const provider = createHookedProviderAdapter({
+    provider: 'fixture',
+    async create(value) { request = value; return { output_text: 'raw', tool_calls: [] }; },
+    async continueWithToolOutputs(value) { return this.create(value); },
+  }, { hookRuntime: hooks });
+  const result = await provider.create({ model: 'initial', input: 'hello' });
+  assert.equal(request.model, 'portable-model');
+  assert.equal(request.temperature, 0);
+  assert.equal(result.output_text, 'redacted');
+});
+
+test('post-hook failures never replay a completed side effect or paid model request', async () => {
+  const receipts = [];
+  const hooks = createHookRuntime({ onReceipt: (receipt) => receipts.push(receipt), hooks: {
+    post_tool_use: { id: 'tool-post', failure_mode: 'error', handler: () => { throw new Error('observer failed'); } },
+    post_model_use: { id: 'model-post', failure_mode: 'error', handler: () => { throw new Error('observer failed'); } },
+    error_occurred: () => ({ error_handling: 'retry', retry_count: 3 }),
+  } });
+  let toolCalls = 0;
+  const capability = createHookedCapabilityAdapter({
+    toolDescriptors: () => [{ name: 'write' }],
+    async invoke() { toolCalls += 1; return { ok: true }; },
+  }, { hookRuntime: hooks });
+  await assert.rejects(capability.invoke('write'), /hook_execution_failed:tool-post/);
+  assert.equal(toolCalls, 1);
+
+  let modelCalls = 0;
+  const provider = createHookedProviderAdapter({
+    provider: 'fixture',
+    async create() { modelCalls += 1; return { output_text: 'paid result', tool_calls: [] }; },
+    async continueWithToolOutputs() { throw new Error('unused'); },
+  }, { hookRuntime: hooks });
+  await assert.rejects(provider.create({ model: 'fixture' }), /hook_execution_failed:model-post/);
+  assert.equal(modelCalls, 1);
+  const failures = receipts.filter((receipt) => receipt.status === 'failed');
+  assert.equal(failures.length, 2);
+  for (const receipt of failures) {
+    assert.equal(receipt.error.failure_behavior, 'no_replay');
+    assert.equal(receipt.error.side_effect_state, 'confirmed_applied');
+    assert.equal(receipt.error.retryable, false);
+  }
+});
+
+test('runtime rejects duplicate hook ids', () => {
+  const runtime = createHookRuntime();
+  runtime.register('session_start', { id: 'same', handler: () => null });
+  assert.throws(() => runtime.register('session_start', { id: 'same', handler: () => null }), /duplicate_hook_id/);
+});

package/packages/agentsam-knowledge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-knowledge",
-  "version": "2.6.9",
+  "version": "2.6.10",
   "description": "Portable AutoRAG discovery, adapter registries, probes, and company routing contracts for AgentSam.",
   "type": "module",
   "exports": {

package/packages/agentsam-nav/dist/Nav.d.ts

@@ -0,0 +1,43 @@
+import { type HTMLAttributes } from 'react';
+import { NavCollapsible, NavCollapsibleContent, NavCollapsibleTrigger } from './NavCollapsible.js';
+import { NavContent } from './NavContent.js';
+import { NavFooter } from './NavFooter.js';
+import { NavGroup, NavGroupLabel } from './NavGroup.js';
+import { NavHeader } from './NavHeader.js';
+import { NavMenu, NavMenuButton, NavMenuChevron, NavMenuItem, NavMenuSub, NavMenuSubButton } from './NavMenu.js';
+import { NavProvider } from './NavProvider.js';
+import { NavTrigger } from './NavTrigger.js';
+import { NavScope, NavSidenav, NavTopbar, NavTopbarLogo, NavTopbarSpacer, NavProjectContext, NavAccountSwitcher, NavFilesResources, NavPinnedSummary, NavConversationActions, NavShareButton, NavOverflowMenu, NavModeSwitcher } from './Surfaces.js';
+declare function NavRoot({ className, children, ...props }: HTMLAttributes<HTMLElement>): import("react").JSX.Element;
+export declare const Nav: typeof NavRoot & {
+    Scope: typeof NavScope;
+    Sidenav: typeof NavSidenav;
+    Topbar: typeof NavTopbar;
+    TopbarLogo: typeof NavTopbarLogo;
+    TopbarSpacer: typeof NavTopbarSpacer;
+    ProjectContext: typeof NavProjectContext;
+    AccountSwitcher: typeof NavAccountSwitcher;
+    FilesResources: typeof NavFilesResources;
+    PinnedSummary: typeof NavPinnedSummary;
+    ConversationActions: typeof NavConversationActions;
+    ShareButton: typeof NavShareButton;
+    OverflowMenu: typeof NavOverflowMenu;
+    ModeSwitcher: typeof NavModeSwitcher;
+    Provider: typeof NavProvider;
+    Header: typeof NavHeader;
+    Content: typeof NavContent;
+    Footer: typeof NavFooter;
+    Group: typeof NavGroup;
+    GroupLabel: typeof NavGroupLabel;
+    Menu: typeof NavMenu;
+    MenuItem: typeof NavMenuItem;
+    MenuButton: typeof NavMenuButton;
+    MenuSub: typeof NavMenuSub;
+    MenuSubButton: typeof NavMenuSubButton;
+    MenuChevron: typeof NavMenuChevron;
+    Collapsible: typeof NavCollapsible;
+    CollapsibleTrigger: typeof NavCollapsibleTrigger;
+    CollapsibleContent: typeof NavCollapsibleContent;
+    Trigger: typeof NavTrigger;
+};
+export {};

package/packages/agentsam-nav/dist/NavCollapsible.d.ts

@@ -0,0 +1,10 @@
+import { type ButtonHTMLAttributes, type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
+export declare function NavCollapsible({ children, defaultOpen }: {
+    children: ReactNode;
+    defaultOpen?: boolean;
+}): import("react").JSX.Element;
+export declare function NavCollapsibleTrigger({ render, children, className, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & {
+    render?: ReactElement;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function NavCollapsibleContent({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavContent.d.ts

@@ -0,0 +1,2 @@
+import type { HTMLAttributes } from 'react';
+export declare function NavContent({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavFooter.d.ts

@@ -0,0 +1,2 @@
+import type { HTMLAttributes } from 'react';
+export declare function NavFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavGroup.d.ts

@@ -0,0 +1,3 @@
+import type { HTMLAttributes } from 'react';
+export declare function NavGroup({ className, ...props }: HTMLAttributes<HTMLElement>): import("react").JSX.Element;
+export declare function NavGroupLabel({ className, ...props }: HTMLAttributes<HTMLParagraphElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavHeader.d.ts

@@ -0,0 +1,2 @@
+import type { HTMLAttributes } from 'react';
+export declare function NavHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavMenu.d.ts

@@ -0,0 +1,22 @@
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
+export declare function NavMenu({ className, ...props }: HTMLAttributes<HTMLUListElement>): import("react").JSX.Element;
+export declare function NavMenuItem({ className, ...props }: HTMLAttributes<HTMLLIElement>): import("react").JSX.Element;
+export type NavMenuButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+    icon?: unknown;
+    active?: boolean;
+    itemId?: string;
+    children: ReactNode;
+};
+export declare function NavMenuButton({ icon: Icon, active, itemId, className, children, ...props }: NavMenuButtonProps): import("react").JSX.Element;
+export declare function NavMenuSub({ className, ...props }: HTMLAttributes<HTMLUListElement>): import("react").JSX.Element;
+export type NavMenuSubButtonProps = {
+    href?: string;
+    active?: boolean;
+    className?: string;
+    children?: unknown;
+    onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+};
+export declare function NavMenuSubButton({ active, className, children, ...props }: NavMenuSubButtonProps): import("react").JSX.Element;
+export declare function NavMenuChevron({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/packages/agentsam-nav/dist/NavProvider.d.ts

@@ -0,0 +1,35 @@
+import { type PropsWithChildren } from 'react';
+import type { NavTheme, NavValue, NavTokens } from './contracts.js';
+export type NavContextValue = {
+    data: NavValue;
+    tokens: NavTokens;
+    theme: NavTheme;
+    accentColor: string;
+    menu: string | null;
+    setMenu: (menu: string | null) => void;
+    open: boolean;
+    isMobile: boolean;
+    isPeeking: boolean;
+    peekable: boolean;
+    resizable: boolean;
+    width: number;
+    mobileBreakpoint: number;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    close: () => void;
+    setPeeking: (peeking: boolean) => void;
+    setWidth: (width: number) => void;
+    scrollToItem: (itemId: string) => void;
+};
+export type NavProviderProps = PropsWithChildren<{
+    value?: NavValue;
+    tokens?: NavTokens;
+    theme?: NavTheme;
+    accentColor?: string;
+    defaultOpen?: boolean;
+    mobileBreakpoint?: number;
+    peekable?: boolean;
+    resizable?: boolean;
+}>;
+export declare function NavProvider({ children, value: data, tokens, theme, accentColor, defaultOpen, mobileBreakpoint, peekable, resizable, }: NavProviderProps): import("react").JSX.Element;
+export declare function useNav(): NavContextValue;

package/packages/agentsam-nav/dist/NavTrigger.d.ts

@@ -0,0 +1,2 @@
+import type { ButtonHTMLAttributes } from 'react';
+export declare function NavTrigger({ className, 'aria-label': ariaLabel, ...props }: ButtonHTMLAttributes<HTMLButtonElement>): import("react").JSX.Element;

package/packages/agentsam-nav/dist/Surfaces.d.ts

@@ -0,0 +1,41 @@
+import { type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import type { NavAccount, NavAction } from './contracts.js';
+export declare function useNavStyle(): CSSProperties;
+export declare function NavScope({ className, style, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
+/** The portal carries its own theme, so standalone surfaces never depend on body CSS. */
+export declare function NavOverflowMenu({ label, actions, children, id: suppliedId, align }: {
+    label?: string;
+    actions?: NavAction[];
+    children?: ReactNode;
+    id?: string;
+    align?: 'start' | 'center' | 'end';
+}): import("react").JSX.Element;
+export declare function NavTopbarLogo({ variant, onClick, toggle }: {
+    variant?: 'mark' | 'expanded';
+    onClick?: () => void;
+    toggle?: boolean;
+}): import("react").JSX.Element;
+export declare function NavProjectContext(): import("react").JSX.Element;
+export declare function NavTopbarSpacer(): import("react").JSX.Element;
+export declare function NavFilesResources(): import("react").JSX.Element;
+export declare function NavPinnedSummary(): import("react").JSX.Element | null;
+export declare function NavConversationActions(): import("react").JSX.Element;
+export declare function NavShareButton(): import("react").JSX.Element | null;
+export declare function NavAccountSwitcher({ accounts, activeAccountId, onAccountChange, expanded }: {
+    accounts?: NavAccount[];
+    activeAccountId?: string;
+    onAccountChange?: (id: string) => void;
+    expanded?: boolean;
+}): import("react").JSX.Element;
+export declare function NavModeSwitcher(): import("react").JSX.Element;
+export declare function NavTopbar({ children, rightSlot, modeSlot, contextSlot, startup, className, showNavigationTrigger, showAccount, }: {
+    children?: ReactNode;
+    rightSlot?: ReactNode;
+    modeSlot?: ReactNode;
+    contextSlot?: ReactNode;
+    startup?: boolean;
+    className?: string;
+    showNavigationTrigger?: boolean;
+    showAccount?: boolean;
+}): import("react").JSX.Element;
+export declare function NavSidenav(): import("react").JSX.Element;

package/packages/agentsam-nav/dist/browser.d.ts

@@ -0,0 +1,11 @@
+import type { NavProviderProps } from './NavProvider.js';
+export interface MountNavOptions extends Omit<NavProviderProps, 'children'> {
+    sidenav?: HTMLElement;
+    topbar?: HTMLElement;
+    startup?: boolean;
+}
+/** Plain HTML integration. Both portals are descendants of the same provider. */
+export declare function mountNav(options: MountNavOptions): {
+    update(next: Partial<MountNavOptions>): void;
+    unmount(): void;
+};