Runtime: compose typed hosted external-context tools

src/__tests__/integration/core/agent-loop.test.ts

@@ -1,11 +1,13 @@
 import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { AgentLoopCheckpointService, AgentLoopRuntimeService } from '@/core/runtime/loop/index.js';
 import { RuntimeToolService } from '@/core/runtime/tools/index.js';
 import { ToolBundleComposer, type ToolToolkit } from '@/core/tools/index.js';
 import { AgentSkillService, FileAgentSkillActivationRepository } from '@/core/skills/index.js';
+import { ProviderCredentialRepository } from '@/core/auth/index.js';
+import { LlmAdapterService } from '@/core/llm/index.js';
 import type { ChatMessage, LlmAdapter, LlmResponse } from '../../../core/llm/types.js';
 import type { AgentHeartbeatEvent, AgentLoopEvent, ToolDefinition } from '../../../advanced.js';
 import { createLogger } from '../../../core/utils/logger.js';
@@ -19,6 +21,90 @@ import {
 const silentLogger = createLogger({ level: 'silent', console: false });
 
 describe('AgentLoopRuntimeService.run', () => {
+  it('constructs an exact host toolkit with the run-scoped OAuth credential', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'heddle-run-toolkit-credential-'));
+    const credentialStorePath = join(root, 'auth.json');
+    new ProviderCredentialRepository({ storePath: credentialStorePath }).set({
+      type: 'oauth',
+      provider: 'openai',
+      accessToken: 'stored-access-token',
+      refreshToken: 'stored-refresh-token',
+      expiresAt: Date.now() + 120_000,
+      accountId: 'account-123',
+      createdAt: '2026-09-07T00:00:00.000Z',
+      updatedAt: '2026-09-07T00:00:00.000Z',
+    });
+
+    let adapterCredential: unknown;
+    let toolkitCredential: unknown;
+    let toolkitCredentialSource: unknown;
+    let modelVisibleTools: string[] = [];
+    const fakeLlm: LlmAdapter = {
+      info: {
+        provider: 'openai',
+        model: 'gpt-5.4',
+        capabilities: {
+          toolCalls: true,
+          systemMessages: true,
+          reasoningSummaries: false,
+          parallelToolCalls: true,
+        },
+      },
+      async chat(_messages, tools): Promise<LlmResponse> {
+        modelVisibleTools = tools.map((tool) => tool.name);
+        return { content: 'Done.' };
+      },
+    };
+    const createLlm = vi.spyOn(LlmAdapterService, 'create').mockImplementation((input) => {
+      adapterCredential = input.credentials?.credential;
+      return fakeLlm;
+    });
+    const toolkit: ToolToolkit = {
+      id: 'host-project-context',
+      createTools(context) {
+        toolkitCredential = context.credential;
+        toolkitCredentialSource = context.providerCredentialSource;
+        return [{
+          name: 'host_context_read',
+          description: 'Read bounded host context.',
+          parameters: { type: 'object', properties: {} },
+          execute: async () => ({ ok: true, output: 'context' }),
+        }];
+      },
+    };
+
+    try {
+      const result = await AgentLoopRuntimeService.run({
+        goal: 'Answer from bounded context.',
+        model: 'gpt-5.4',
+        credentialStorePath,
+        includeDefaultTools: false,
+        toolkits: [toolkit],
+        maxSteps: 1,
+        logger: silentLogger,
+        workspaceRoot: root,
+      });
+
+      expect(result.outcome).toBe('done');
+    } finally {
+      createLlm.mockRestore();
+    }
+
+    expect(adapterCredential).toMatchObject({
+      type: 'oauth-access-token',
+      provider: 'openai',
+      accessToken: 'stored-access-token',
+      accountId: 'account-123',
+    });
+    expect(toolkitCredential).toBe(adapterCredential);
+    expect(toolkitCredentialSource).toMatchObject({
+      type: 'oauth-access-token',
+      provider: 'openai',
+      accountId: 'account-123',
+    });
+    expect(modelVisibleTools).toEqual(['host_context_read']);
+  });
+
   it('runs through the public execution loop and emits loop events around trace events', async () => {
     const workspaceRoot = resolve('/tmp/heddle-loop-test');
     const seenMessages: ChatMessage[][] = [];

src/__tests__/integration/core/heartbeat-runner-credentials.test.ts

@@ -54,13 +54,14 @@ describe('custom heartbeat runner credentials', () => {
       credentials: {
         apiKey: undefined,
         credential: expect.objectContaining({
-          type: 'oauth',
+          type: 'oauth-access-token',
           provider: 'openai',
           accessToken: 'stored-access-token',
         }),
         credentialStorePath,
       },
     }));
+    expect(createAdapter.mock.calls[0]?.[0].credentials?.credential).not.toHaveProperty('refreshToken');
 
     const externallyVisibleState = JSON.stringify({
       tasks: execution.savedTasks,

src/__tests__/integration/tools/tools.test.ts

@@ -1,4 +1,5 @@
 import { mkdtemp, mkdir, readFile, realpath, symlink, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -777,6 +778,169 @@ describe('viewImageTool', () => {
     });
   });
 
+  it('fails closed when a host does not authorize an opaque image reference', async () => {
+    const resourceResolver = vi.fn().mockResolvedValue(null);
+    const tool = createViewImageTool({ resourceResolver });
+
+    const result = await tool.execute({ reference: 'image-123' });
+
+    expect(result).toEqual({
+      ok: false,
+      error: 'Image view failed: The host did not authorize or resolve the requested image reference.',
+    });
+    expect(resourceResolver).toHaveBeenCalledWith('image-123', {});
+  });
+
+  it('rejects unsupported host-resolved media before any provider call', async () => {
+    const tool = createViewImageTool({
+      resourceResolver: async () => ({
+        bytes: Buffer.from('not-an-image'),
+        mediaType: 'application/octet-stream',
+      }),
+    });
+
+    const result = await tool.execute({ reference: 'image-123' });
+
+    expect(result).toEqual({
+      ok: false,
+      error: 'Image view failed: Host-resolved images must use image/png, image/jpeg, image/gif, or image/webp.',
+    });
+  });
+
+  it('bounds host-resolved image streams before provider invocation', async () => {
+    const tool = createViewImageTool({
+      maxImageBytes: 4,
+      resourceResolver: async () => ({
+        bytes: (async function* () {
+          yield Buffer.from('123');
+          yield Buffer.from('45');
+        })(),
+        mediaType: 'image/png',
+      }),
+    });
+
+    const result = await tool.execute({ reference: 'image-123' });
+
+    expect(result).toEqual({
+      ok: false,
+      error: 'Image view failed: Image exceeds the configured 4-byte inspection limit.',
+    });
+  });
+
+  it.each([
+    {
+      label: 'byte count',
+      metadata: { byteSize: 100 },
+      error: 'Image view failed: Host-resolved image byte count does not match its metadata.',
+    },
+    {
+      label: 'SHA-256',
+      metadata: { checksumSha256: '0'.repeat(64) },
+      error: 'Image view failed: Host-resolved image failed its SHA-256 integrity check.',
+    },
+  ])('rejects mismatched host-resolved $label metadata', async ({ metadata, error }) => {
+    const tool = createViewImageTool({
+      resourceResolver: async () => ({
+        bytes: Buffer.from('image-bytes'),
+        mediaType: 'image/png',
+        ...metadata,
+      }),
+    });
+
+    await expect(tool.execute({ reference: 'image-123' })).resolves.toEqual({
+      ok: false,
+      error,
+    });
+  });
+
+  it('honors cancellation before resolving host image content', async () => {
+    const controller = new AbortController();
+    controller.abort(new Error('cancelled by host'));
+    const resourceResolver = vi.fn();
+    const tool = createViewImageTool({ resourceResolver });
+
+    const result = await tool.execute({ reference: 'image-123' }, { signal: controller.signal });
+
+    expect(result).toEqual({
+      ok: false,
+      error: 'Image view failed: cancelled by host',
+    });
+    expect(resourceResolver).not.toHaveBeenCalled();
+  });
+
+  it('inspects host-resolved bytes directly with request-scoped credentials', async () => {
+    const bytes = Buffer.from('host-owned-image-bytes');
+    const credential = {
+      type: 'oauth-access-token',
+      provider: 'openai',
+      accessToken: 'request-access-token',
+      expiresAt: Date.now() + 120_000,
+      accountId: 'account-123',
+    } as const;
+    const resourceResolver = vi.fn(async () => ({
+      bytes: (async function* () {
+        yield bytes.subarray(0, 8);
+        yield bytes.subarray(8);
+      })(),
+      mediaType: 'image/png',
+      byteSize: bytes.byteLength,
+      checksumSha256: createHash('sha256').update(bytes).digest('hex'),
+    }));
+    const requests: Array<{ headers: Headers; body: string }> = [];
+    vi.stubGlobal('fetch', vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
+      requests.push({
+        headers: new Headers(init?.headers),
+        body: String(init?.body ?? ''),
+      });
+      return new Response([
+        'event: response.output_text.done',
+        'data: {"type":"response.output_text.done","text":"Stored project image.","content_index":0,"item_id":"msg_1","output_index":0,"sequence_number":1}',
+        '',
+        'event: response.completed',
+        'data: {"type":"response.completed","response":{"id":"resp_1","status":"completed","model":"gpt-5.4","output_text":"Stored project image.","output":[]}}',
+        '',
+      ].join('\n'), {
+        status: 200,
+        headers: { 'content-type': 'text/event-stream' },
+      });
+    }));
+    const tool = createViewImageTool({
+      model: 'gpt-5.4',
+      credential,
+      providerCredentialSource: {
+        type: 'oauth-access-token',
+        provider: 'openai',
+        expiresAt: credential.expiresAt,
+        accountId: credential.accountId,
+      },
+      resourceResolver,
+    });
+
+    const result = await tool.execute({
+      reference: 'image-123',
+      prompt: 'Describe the stored image.',
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      output: {
+        provider: 'openai',
+        model: 'gpt-5.4',
+        reference: 'image-123',
+        summary: 'Stored project image.',
+      },
+    });
+    expect(resourceResolver).toHaveBeenCalledWith('image-123', {});
+    expect(requests).toHaveLength(1);
+    expect(requests[0]?.headers.get('authorization')).toBe('Bearer request-access-token');
+    const body = JSON.parse(requests[0]?.body ?? '{}') as {
+      input?: Array<{ content?: Array<{ image_url?: string }> }>;
+    };
+    expect(body.input?.[0]?.content?.[1]?.image_url).toBe(
+      `data:image/png;base64,${bytes.toString('base64')}`,
+    );
+  });
+
   it('fails clearly when no OpenAI key is available for the default provider', async () => {
     const root = await mkdtemp(join(tmpdir(), 'heddle-view-image-'));
     const imagePath = join(root, 'screen.png');

src/__tests__/unit/tools/external-context-contracts.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { ToolInput, ToolOutput } from '@/core/types.js';
+import {
+  createWebSearchTool,
+  type WebSearchToolDefinition,
+} from '@/core/tools/toolkits/external-context/web-search.js';
+import {
+  createViewImageTool,
+  type ViewImageToolDefinition,
+} from '@/core/tools/toolkits/external-context/view-image.js';
+import {
+  MAX_EXTERNAL_CONTEXT_PROMPT_LENGTH,
+  MAX_VIEW_IMAGE_INPUTS,
+  MAX_WEB_SEARCH_CITATIONS,
+  ViewImageInputSchema,
+  ViewImageOutputSchema,
+  WebSearchInputSchema,
+  WebSearchOutputSchema,
+  type ViewImageInput,
+  type ViewImageOutput,
+  type WebSearchInput,
+  type WebSearchOutput,
+} from '@/core/tools/toolkits/external-context/schemas.js';
+
+describe('external-context public contracts', () => {
+  it('preserves built-in input and output types through ToolDefinition', () => {
+    expectTypeOf<ToolInput<WebSearchToolDefinition>>().toEqualTypeOf<WebSearchInput>();
+    expectTypeOf<ToolOutput<WebSearchToolDefinition>>().toEqualTypeOf<WebSearchOutput>();
+    expectTypeOf<ToolInput<ViewImageToolDefinition>>().toEqualTypeOf<ViewImageInput>();
+    expectTypeOf<ToolOutput<ViewImageToolDefinition>>().toEqualTypeOf<ViewImageOutput>();
+  });
+
+  it('publishes the exact schemas used by each tool definition', () => {
+    const search = createWebSearchTool();
+    const image = createViewImageTool();
+
+    expect(search.inputSchema).toBe(WebSearchInputSchema);
+    expect(search.outputSchema).toBe(WebSearchOutputSchema);
+    expect(image.inputSchema).toBe(ViewImageInputSchema);
+    expect(image.outputSchema).toBe(ViewImageOutputSchema);
+  });
+
+  it('validates and normalizes bounded web search inputs', () => {
+    expect(WebSearchInputSchema.parse({
+      query: '  current runtime docs  ',
+      contextSize: 'high',
+    })).toEqual({
+      query: 'current runtime docs',
+      contextSize: 'high',
+    });
+    expect(WebSearchInputSchema.safeParse({
+      query: 'x'.repeat(MAX_EXTERNAL_CONTEXT_PROMPT_LENGTH + 1),
+    }).success).toBe(false);
+    expect(WebSearchInputSchema.safeParse({ query: 'docs', unexpected: true }).success).toBe(false);
+    expect(WebSearchOutputSchema.safeParse({
+      provider: 'openai',
+      model: 'gpt-test',
+      summary: 'summary',
+      citations: [{ title: 'unsafe', url: 'javascript:alert(1)' }],
+    }).success).toBe(false);
+  });
+
+  it('bounds web search citations and image inputs in the canonical schemas', () => {
+    const citation = { title: 'Heddle', url: 'https://heddleagent.com' };
+    expect(WebSearchOutputSchema.safeParse({
+      provider: 'openai',
+      model: 'gpt-test',
+      summary: 'summary',
+      citations: Array.from({ length: MAX_WEB_SEARCH_CITATIONS + 1 }, () => citation),
+    }).success).toBe(false);
+    expect(ViewImageInputSchema.safeParse({
+      references: Array.from({ length: MAX_VIEW_IMAGE_INPUTS + 1 }, (_, index) => `image-${index}`),
+    }).success).toBe(false);
+    expect(ViewImageInputSchema.safeParse({ prompt: 'no image' }).success).toBe(false);
+    expect(ViewImageOutputSchema.safeParse({
+      provider: 'openai',
+      model: 'gpt-test',
+      summary: 'summary',
+    }).success).toBe(false);
+  });
+});