ToolJournal

CORE · interface · Type contract

Request-local execution receipts; the host decides their domain content.

Import

TypeScript

import type { ToolJournal } from '@jangts/agent-core/tools';

JavaScript

/** @typedef {import('@jangts/agent-core/tools').ToolJournal} ToolJournal */

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/structs, @jangts/agent-core/tools, @jangts/agent-core/kits/tools, @jangts/agent-core/kits.

Definition

interface ToolJournal

Field structure

Field	Type	Required	Description
beginTool	(request: ToolJournalStart) => string	Required	Opens a receipt and returns the invocation id later passed to finishTool.
finishTool	(request: ToolJournalFinish) => void	Required	Closes the receipt; must be called exactly once per opened invocation.

Member index

Member	Purpose
beginTool	Opens a receipt and returns the invocation id later passed to finishTool.
finishTool	Closes the receipt; must be called exactly once per opened invocation.

Member details

beginTool

Opens a receipt and returns the invocation id later passed to finishTool.

ToolJournal.beginTool(request: ToolJournalStart): string

Opens a receipt and returns the invocation id later passed to finishTool.

Parameter	Type	Passing	Description
request	ToolJournalStart	Required	—

Fields of request

Field	Type	Required	Description
toolId	string	Required	Tool being invoked.
input	unknown	Required	Parsed input; stored as-is so the host can build its own domain record.
invocation	Partial<InvocationMetadata> | undefined	Optional	What the caller already knows. The journal fills gaps and generates an id when absent.

Returns: string.

finishTool

Closes the receipt; must be called exactly once per opened invocation.

ToolJournal.finishTool(request: ToolJournalFinish): void

Closes the receipt; must be called exactly once per opened invocation.

Parameter	Type	Passing	Description
request	ToolJournalFinish	Required	—

Fields of request

Field	Type	Required	Description
invocationId	string	Required	Invocation opened by beginTool.
status	"error" | "success" | "cancelled"	Required	Terminal status; cancelled is distinct from error.
value	unknown	Required	Produced value on success; failure detail on error; ignored for cancellation.

Returns: void.

Examples

• Synchronous execution adapter for host-selected invocations: Record start, completion, and failure uniformly for synchronous invocations the host has already selected, without replacing tool selection or authorization.

Execute a local invocation the App has already selected

Beginner · Node.js

TypeScript

import { executeInvocation } from '@jangts/agent-core/tools';
const state = { status: '' };
executeInvocation({ id: 'read-status', call(_input: {}, context: typeof state) {
  context.status = '服务正常';
} }, {}, state);
console.log(state.status);

JavaScript

import { executeInvocation } from '@jangts/agent-core/tools';
const state = { status: '' };
executeInvocation({ id: 'read-status', call(_input, context) {
        context.status = '服务正常';
    } }, {}, state);
console.log(state.status);

Connect the same request journal and cancellation signal

Configuration · Node.js

TypeScript

import { executeInvocation } from '@jangts/agent-core/tools';
import { ContextJournal } from '@jangts/agent-core/journal';
const state = { status: '', journal: new ContextJournal(), signal: new AbortController().signal };
executeInvocation({ id: 'read-status', call(_input: {}, context: typeof state) { context.status = '服务正常'; } }, {}, state, {
  signal: context => context.signal,
  journal: context => context.journal,
  receipt: context => context.status,
});
console.log(state.journal.snapshot());

JavaScript

import { executeInvocation } from '@jangts/agent-core/tools';
import { ContextJournal } from '@jangts/agent-core/journal';
const state = { status: '', journal: new ContextJournal(), signal: new AbortController().signal };
executeInvocation({ id: 'read-status', call(_input, context) { context.status = '服务正常'; } }, {}, state, {
    signal: context => context.signal,
    journal: context => context.journal,
    receipt: context => context.status,
});
console.log(state.journal.snapshot());

Related policy source

• Boundaries of synchronous invocation, cancellation, and receipts

Related definitions

• ToolJournalFinish
• ToolJournalStart