Skip to content
SHAMPOO

Tool catalogue

session_save

Write · Ordinary · Sessions and context

session_save

  • Category: sessions
  • Access: write
  • Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Saves a session snapshot, creating it on first call and updating it on later calls with the same id. The durable handoff surface: project, summary, and active files persist beyond the current run.

Arguments

Optional: active_files, project, session_id, summary.

  • active_files. Note: Empty, missing, or null stores as null; otherwise the file list is stored as JSON text.
  • project. Note: Supplied projects must be granted now. An omitted project on creation is an untagged write needing the untagged grant; on update, unmentioned fields are left untouched.
  • session_id. Note: Omit or blank for a fresh server-assigned UUID; a malformed explicit id is rejected. All forms the platform UUID parser accepts are honored.
  • summary.

Result

JSON object with action (created or updated) and session_id. Denied updates answer with an error object reading session not found rather than revealing the session.

Boundaries

A session's current project must be writable by the caller, and callers without star scope may only touch sessions owned by their own principal; anything else reads as session not found. Operates only inside the caller's profile boundary.

Lifecycle / side effects

Create-or-update by session id through one atomic unit, recording the write with the caller's identity. ended_at is always stamped to the current time on both paths; updates keep prior project, summary, and file values wherever the call supplies nothing.

Errors

Bad session_id, project, summary, or active_files types are rejected (strict validator). A malformed session_id answers session_id must be a UUID returned by session_save. Out-of-scope projects and foreign sessions deny generically. Failures persist nothing (atomic).

Example

{
  "project": "shared-ops",
  "summary": "Pack README drafted; left proofing for next run."
}

Result shape:

{
  "action": "created",
  "session_id": "<uuid>"
}

session_id is assigned by the server when omitted; the placeholder stands for the returned UUID.

See also

session_recall, ready_context, task_digest, query_tasks.

On this page