API Reference

Common patterns

All tools return a PartialToolResult with shape:

{
    status: ResultStatus.Success | ResultStatus.Error;
    result: string; // JSON string on success, error message on failure
    tool: string; // tool name, e.g. "start_stopwatch"
}

Time values (duration, remaining, elapsed) are returned as human-readable strings via pretty-ms (e.g. "5m", "1h 30m", "12.34s").

TimeTool

Returns the current date/time information or calculates a timespan between two ISO 8601 datetimes.

Tool name: time

Parameters:

Parameter	Type	Required	Description
`from`	string	no	Start datetime (ISO 8601). Required if `to` is given.
`to`	string	no	End datetime (ISO 8601). Requires `from`.

Returns (no params): JSON with iso, locale, date, time, timezone, unix_ms, year, month, month_name, day_of_month, day_of_week, day_of_week_name, day_of_year, hours, minutes, seconds, milliseconds.

Returns (from only): { from, now, elapsed } where elapsed is a human-readable duration (e.g. "1h 30m").

Returns (from + to): { from, to, timespan } where timespan is a human-readable duration (e.g. "1d 1h 30m").

Stopwatch Tools

Three tools for measuring elapsed time. Stopwatches start from 0 and count up.

StopwatchPool

Manages stopwatch instances. Pass an instance to tool constructors.

import { StopwatchPool } from 'llm-chat-time';
const pool = new StopwatchPool();

StartStopwatchTool

Creates and immediately starts a new stopwatch.

Tool name: start_stopwatch

Parameters: None

Returns: { stopwatch_id: "stopwatch-N" }

StopStopwatchTool

Stops and removes a stopwatch, returning the elapsed time.

Tool name: stop_stopwatch

Parameters:

Parameter	Type	Required	Description
`stopwatch_id`	string	yes	ID of the stopwatch to stop and remove.

Returns: { stopwatch_id, elapsed: "5m 30s" }

ListStopwatchesTool

Lists all stopwatches with their current state and elapsed time.

Tool name: list_stopwatches

Parameters: None

Returns: { stopwatches: [{ id, running, elapsed }] }

Timer Tools

Five tools for countdown timers. start_timer creates, configures, and starts a timer in a single call. On expiry the timer auto-removes from the pool. Use cancel_timer to stop and remove a timer early.

TimerPool

Manages all timers — create, list, get, remove, clear.

import { TimerPool } from 'llm-chat-time';
const pool = new TimerPool(myTimerService);

Timer

The Timer domain class handles countdown state, expiry notification, and auto-removal.

import { Timer } from 'llm-chat-time';
const timer = new Timer('my-timer', myService);

Properties:

Property	Type	Description
`id`	`string`	Timer identifier.
`durationMs`	`number`	Duration in milliseconds.
`remaining`	`number`	Remaining milliseconds.
`running`	`boolean`	Whether the timer is currently counting down.
`reminder`	`string \\| undefined`	Reminder text set at start.
`service`	`TimerService`	Service injected via `TimerPool` for expiry notification.

TimerService interface:

interface TimerService {
    notify(event: TimerEvent): Promise<void>;
}

When the timer expires, it calls service.notify(event). See the Quick Start for wiring examples.

StartTimerTool

Creates, configures, and starts a countdown timer in a single call. The timer auto-removes when it expires.

Tool name: start_timer

Parameters:

Parameter	Type	Required	Description
`time`	string	yes	Duration string (e.g. `"5m"`, `"1h30m"`, `"2 days 5 hours"`).
`reminder`	string	no	Text to surface when the timer expires.

Returns: { timer_id, scheduled_end_at }

CancelTimerTool

Cancels and removes a timer by id. Running timers are stopped first.

Tool name: cancel_timer

Parameters:

Parameter	Type	Required	Description
`timer_id`	string	yes	ID of the timer to cancel.

Returns: { timer_id, status: "cancelled" }

GetTimerTool

Returns the current state of a timer by id.

Tool name: get_timer

Parameters:

Parameter	Type	Required	Description
`timer_id`	string	yes	ID of the timer to get.

Returns: { timer_id, running, duration, remaining, reminder? }

ListTimersTool

Lists all timers with their current state and remaining time.

Tool name: list_timers

Parameters: None

Returns: { timers: [{ id, running, duration, remaining, reminder? }] }

Package classes

The package classes group related tools for registration with the llm-chat framework. All implement the ToolPackage interface from @johannes.latzel/llm-chat.

StopwatchPackage

Groups the three stopwatch tools. Creates a default StopwatchPool if none is provided.

import { StopwatchPackage } from 'llm-chat-time';
const pkg = new StopwatchPackage();
// or with an existing pool:
const pkg = new StopwatchPackage(myPool);

Tools: start, stop, list (3 tools)
Constructor: optional StopwatchPool
dispose(): not implemented

TimerPackage

Groups the five timer tools. Creates a default TimerPool (with a console.log-based expiry handler) if none is provided.

import { TimerPackage } from 'llm-chat-time';
const pkg = new TimerPackage();
// or with an existing pool:
const pkg = new TimerPackage(myPool);

Tools: start, get, list, cancel, timer_expired (5 tools)
Constructor: optional TimerPool
dispose(): not implemented

TimePackage

Composite package that bundles the time tool together with the stopwatch and timer sub-packages. Aggregates all 9 tools.

import { TimePackage } from 'llm-chat-time';
const pkg = new TimePackage();
// or with existing pools:
const pkg = new TimePackage(timerPool, stopwatchPool);

Tools: time, start_stopwatch, stop_stopwatch, list_stopwatches, start_timer, get_timer, list_timers, cancel_timer, timer_expired (9 tools)
Constructor: optional TimerPool, optional StopwatchPool
dispose(): implemented — calls dispose?.() on each sub-package