Scheduling

cron_add

Schedule a recurring prompt to run on a cron expression. The prompt is sent to the LLM in the background at each scheduled time and the response is printed to the console.

Parameters:

Parameter	Type	Required	Description
`schedule`	string	Yes	5-field cron expression (e.g. `"/15 * * "` for every 15 min, `"0 9 * 1-5"` for weekdays at 09:00)
`prompt`	string	Yes	Prompt to send to the LLM at each scheduled time
`name`	string	No	Human-readable label used when listing or removing the job
`context`	string	No	Execution mode: `"fresh"` (default) runs isolated, `"inherit"` reuses the current session history and tools when the host process provides a runner

Returns: Job summary including the assigned 8-character ID, schedule, and next run time.

cron_list

List all scheduled cron jobs.

Parameters: None

Returns: Table of job ID, name, schedule expression, context, run count, last run, and next run time.

cron_remove

Remove a scheduled cron job. Accepts the job ID, a name substring, or the schedule expression.

Parameters:

Parameter	Type	Required	Description
`job_id`	string	Yes	Job ID (8-char hex from `cron_add`), case-insensitive substring of the job name, or exact cron schedule expression

If multiple jobs match by name or schedule, all are removed. If the ID is not remembered, use cron_list first or pass the name given at creation time.

Returns: Confirmation listing removed job IDs and names, or an error message if no match was found.

schedule_reply

Schedule a reply for delayed delivery instead of sending immediately.

Note: This tool is documented for reference but is not yet registered in the static tool registry. It is injected dynamically by the MessageHandler in assistant mode. Do not rely on it being available via request_tools until it has a TOOL_CONFIG registration.

When Used: The agent calls this tool when the system prompt includes timing or scheduling instructions (e.g., “reply in 3 hours”, “respond after the meeting”). The agent’s response is NOT sent immediately — it is queued and delivered by a background thread.

Parameters:

Parameter	Type	Required	Description
`text`	string	Yes	The reply message to send later
`delay_minutes`	int	Yes	Minutes to wait before sending (1–1440)

Notes:

Message text is sanitized through output guardrails before being queued
Delivery retries up to 3 times with exponential backoff (30 s → 120 s → 600 s) on send failure
A new incoming message from the same chat cancels any pending scheduled replies for that chat
Quiet hours are enforced at dispatch time — delivery defers to the end of the quiet window rather than being dropped
Queue is persisted to data/assistant/schedule.json and survives restarts
Configurable via services.assistant.response_timing (quiet hours, per-contact overrides)

Returns: Confirmation string telling the agent not to repeat the message.

Note: In assistant mode, additional message management tools are available: queue_reply, edit_last_reply, list_scheduled_messages, edit_scheduled_message, cancel_scheduled_message, defer_processing, and suppress_reply. These are injected per-call and documented in the Architecture Guide.

Calendar Tools

calendar_list_events

List calendar events within a date range.

Configuration: Requires services.calendar.credentials_file or services.calendar.token_json in .cogtrix.yml.

Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date (ISO 8601, e.g., `2026-05-17`)
`end_date`	string	Yes	End date (ISO 8601)
`calendar_id`	string	No	Specific calendar ID (default: primary)

Returns: List of events with title, start/end times, attendees, and location.

calendar_create_event

Create a new calendar event.

Parameters:

Parameter	Type	Required	Description
`title`	string	Yes	Event title
`start_time`	string	Yes	Start time (ISO 8601 datetime)
`end_time`	string	Yes	End time (ISO 8601 datetime)
`description`	string	No	Event description
`location`	string	No	Location string
`attendees`	array[string]	No	Email addresses of attendees
`calendar_id`	string	No	Target calendar (default: primary)

Returns: Created event with ID and Google Calendar link.

calendar_search_events

Search calendar events by text query.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Search text (matches title, description, location)
`start_date`	string	No	Limit to events on or after this date
`end_date`	string	No	Limit to events on or before this date
`calendar_id`	string	No	Specific calendar ID

Returns: Matching events with title, times, and description excerpt.

Goal Management

set_goal

Set a top-level goal for the current session. Goals are tracked across turns and guide the agent’s priorities.

Parameters:

Parameter	Type	Required	Description
`goal`	string	Yes	Goal description
`deadline`	string	No	Target completion time (ISO 8601)
`priority`	string	No	`high`, `medium`, or `low` (default: `medium`)

Returns: Confirmation with goal ID.

add_subgoal

Add a subgoal under an existing goal.

Parameters:

Parameter	Type	Required	Description
`goal_id`	string	Yes	ID of the parent goal
`subgoal`	string	Yes	Subgoal description
`deadline`	string	No	Target completion time

Returns: Confirmation with subgoal ID.

complete_goal

Mark a goal or subgoal as completed.

Parameters:

Parameter	Type	Required	Description
`goal_id`	string	Yes	ID of the goal or subgoal to complete
`result`	string	No	Outcome summary

Returns: Confirmation and remaining open subgoals (if any).

abandon_goal

Mark a goal or subgoal as abandoned.

Parameters:

Parameter	Type	Required	Description
`goal_id`	string	Yes	ID of the goal or subgoal to abandon
`reason`	string	No	Reason for abandoning

Returns: Confirmation.

list_goals

List all active goals and subgoals with their status.

Parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter: `active`, `completed`, `abandoned`, or `all` (default: `active`)

Returns: Table of goal IDs, descriptions, statuses, and deadlines.