Operation Scratchpad Tool

The manage_assistant_operation tool gives the assistant persistent working memory for bulk operations. When a user asks “send a follow-up to 50 contacts,” the assistant tracks which contacts have been processed, which failed, and where to resume — even after earlier messages leave the context window.

Tool Summary

Field	Value
Tool name	manage_assistant_operation
Permissions	None (manages assistant’s own state, not user data)
Direction	Read/Write
Always available	Yes — no ABAC gate

Architecture

The scratchpad has three layers:

1. Database table — assistant_operation stores canonical state per conversation
2. Tool — manage_assistant_operation lets the assistant read and write its own state
3. System prompt injection — a compact operation summary is rebuilt from the database every turn, so it’s never evicted from context

Actions

The tool supports six actions:

create

Start a new bulk operation. If an active operation already exists in the conversation, it’s automatically paused.

{
  "action": "create",
  "operation_type": "send_sms",
  "total_items": 25,
  "item_ids": ["id-1", "id-2", "..."],
  "batch_size": 5,
  "query_params": { "tag": "Lead", "status": "active" },
  "notes": "Follow-up campaign for Q2 leads"
}

Parameter	Type	Required	Description
operation_type	string	Yes	Label like "send_sms", "update_contacts"
total_items	integer	Yes	Total item count — must match item_ids length
item_ids	string[]	Yes	Full list of IDs to process
batch_size	integer	No	Items per batch (default: 5)
query_params	object	No	Original filter params for pause/resume
notes	string	No	Freeform notes

progress

Get the current state and the next batch of IDs to process.

{
  "action": "progress",
  "operation_id": "optional — auto-detects the active operation if omitted"
}

Returns the next batch of IDs sliced from item_ids starting at the current cursor position, plus counts for completed, failed, and remaining items.

update

Record results after processing a batch.

{
  "action": "update",
  "operation_id": "uuid",
  "completed_ids": ["id-1", "id-2"],
  "failed": [{ "id": "id-3", "reason": "invalid phone number" }]
}

Advances the cursor, increments completed_count and failed_count, and merges results into state_json.

complete

Mark the operation as done. Removes it from the system prompt.

{
  "action": "complete",
  "operation_id": "uuid"
}

resume

Reactivate a paused operation. Auto-pauses the currently active operation if one exists.

{
  "action": "resume",
  "operation_id": "uuid"
}

cancel

Abort the operation. Returns final counts for completed, failed, and abandoned items.

{
  "action": "cancel",
  "operation_id": "uuid"
}

Database Schema

The assistant_operation table:

Column	Type	Description
id	UUID (PK)	Operation ID
conversation_id	UUID (FK)	Links to assistant_conversation
organization_id	UUID (FK)	Links to organization
operation_type	VARCHAR(64)	Human-readable label
status	VARCHAR(32)	active, paused, completed, or cancelled
total_items	INTEGER	Total items in the operation
completed_count	INTEGER	Items processed successfully
failed_count	INTEGER	Items that failed
state_json	JSONB	Full state: item_ids, cursor, completed_ids, failed, batch_size, query_params
created_at	TIMESTAMPTZ	Creation timestamp
updated_at	TIMESTAMPTZ	Last update timestamp

Indexes:

• idx_assistant_operation_conversation — B-tree on conversation_id
• idx_assistant_operation_org_active — partial index on (organization_id, status) where status = 'active'

Both foreign keys cascade on delete.

Behavior Rules

• The assistant must create an operation for any bulk action involving more than 5 items
• Only one operation can be active per conversation — creating or resuming one auto-pauses the current
• The system prompt includes a compact summary of active and paused operations on every turn
• After context eviction, the assistant reads the injected summary to know where to resume

End-to-End Flow

1. User asks: “Send a follow-up SMS to all contacts tagged Lead”
2. Assistant searches contacts → gets 30 results
3. Assistant calls create with all 30 contact IDs
4. Assistant calls progress → gets the first batch of 5 IDs
5. Assistant processes the batch (sends SMS to each)
6. Assistant calls update with completed and failed IDs
7. Repeat steps 4–6 until all items are processed
8. Assistant calls complete

If the user says “continue” after context eviction, the assistant reads the operation summary from the system prompt and resumes from the correct cursor position.