Documentation
¶
Overview ¶
session_push_summary.go is the inline-summarization endpoint: it accepts a summary JSON produced by the calling agent (in response to the summary_prompt returned by `ox session stop`), validates and enriches it, then commits and pushes summary.json to the ledger.
Why two execution sites exist for summarization ¶
Delegating summarization back to the calling agent is the right default *technically*: the agent already has the conversation in context (so input tokens are effectively free), no extra binary is required, and it works for every supported agent (Claude Code, Cursor, Aider, Codex CLI, …).
But it blocks the user at exactly the wrong moment. They have just signaled "I'm done" and want to close the agent or `/clear` and move on; an inline LLM call holds them in the foreground for 30–120s for a ~1–4KB JSON output. We should only force the inline path when the user has not specified (and ox cannot auto-detect) an LLM agent for daemon callouts.
The daemon-side equivalent lives in `internal/daemon/agentwork/session_finalize.go` and calls back into the shared `pushSummaryToLedger` flow below — so prompt construction and validation live in exactly one place. Today the dispatch is gated behind `SAGEOX_ASYNC_SESSION_UPLOAD=1` (see `cmd/ox/agent_session.go`); the plan is to lift that to a first-class `agent.summarizer` user-config key with `auto` as the default.
See ADR-016 (docs/adr/ADR-016-session-summarization-delegation.md) for the full rationale, behavior matrix, and tradeoffs.
session_repair_meta_summary.go is the ox-l4mj retro-cleanup tool.
Even after the producer-side fixes (ox-qqka, ox-wstd) ship, every existing ledger carries the leak forever unless retro-cleared. This command walks the ledger and fixes the on-disk truth: clears validator-error strings from meta.summary / meta.title, recovers a good title from summary.json when available, and stamps SummaryStatus so consumers don't have to keep sniffing for sentinel strings.
Idempotent and safe to run repeatedly. Designed to be invoked both from the CLI and (later) from the daemon's anti-entropy loop.
session_upload.go handles uploading session artifacts to the ledger.
AUTH MODEL: Upload uses Git PAT only (no OAuth required).
- LFS upload: PAT via HTTP Basic auth (getLFSClient)
- git push: PAT embedded in remote URL (RefreshRemoteCredentials)
- checkUploadAccess: OAuth-based, fail-open, kept for viewer detection only
See docs/ai/specs/session-auth-model.md for the full auth model.
Source Files
¶
- adapter.go
- agent.go
- agent_doctor.go
- agent_hook.go
- agent_hooks.go
- agent_instances.go
- agent_prime.go
- agent_prime_context_trace.go
- agent_prime_xml.go
- agent_query.go
- agent_redact.go
- agent_session.go
- agent_session_abort.go
- agent_session_capture_prior.go
- agent_session_context_trace.go
- agent_session_delete.go
- agent_session_incremental.go
- agent_session_log.go
- agent_session_plan_history.go
- agent_session_recover.go
- agent_session_subagent.go
- agent_team_ctx.go
- agent_version.go
- banner.go
- cart_analyze.go
- carts.go
- code.go
- code_activity.go
- code_insights.go
- config.go
- config_get.go
- config_settings.go
- config_tui.go
- coworker.go
- daemon.go
- dashboard.go
- discussion_url.go
- distill.go
- distill_citations.go
- distill_discussions.go
- distill_github.go
- distill_history.go
- distill_history_citations_bridge.go
- distill_history_envelope.go
- distill_history_list.go
- distill_history_show.go
- distill_history_since.go
- distill_history_time.go
- distill_index.go
- distill_sessions.go
- distill_write.go
- docs.go
- doctor.go
- doctor_adapter_blocks.go
- doctor_adapters.go
- doctor_agent.go
- doctor_agent_worker.go
- doctor_auth.go
- doctor_backup_cleanup.go
- doctor_check_registry.go
- doctor_codedb.go
- doctor_commands.go
- doctor_credential_integrity.go
- doctor_daemon.go
- doctor_daemon_dedup.go
- doctor_ecosystem.go
- doctor_fix_hooks.go
- doctor_git.go
- doctor_git_commit_hooks.go
- doctor_git_credentials.go
- doctor_git_repos.go
- doctor_git_repos_fix.go
- doctor_git_repos_validate.go
- doctor_github_migrate.go
- doctor_guidance.go
- doctor_header.go
- doctor_hooks.go
- doctor_init_reverted.go
- doctor_integration.go
- doctor_ledger_git.go
- doctor_ledger_infra.go
- doctor_pat_liveness.go
- doctor_proactive.go
- doctor_project.go
- doctor_registry.go
- doctor_registry_example.go
- doctor_sageox.go
- doctor_sageox_remote.go
- doctor_session.go
- doctor_session_commit.go
- doctor_session_ids.go
- doctor_session_incomplete.go
- doctor_session_uncommitted.go
- doctor_session_upload_retry.go
- doctor_team.go
- doctor_timezone_scrub.go
- doctor_types.go
- doctor_whisper.go
- fetch.go
- friction.go
- git_helpers.go
- glance.go
- heartbeat.go
- hooks_agent.go
- hooks_agentsmd.go
- hooks_amp.go
- hooks_claude.go
- hooks_cmd.go
- hooks_codex.go
- hooks_commit_msg.go
- hooks_events_add.go
- hooks_events_list.go
- hooks_events_log.go
- hooks_events_test_cmd.go
- hooks_external.go
- hooks_gemini.go
- hooks_git.go
- hooks_opencode.go
- hooks_pi.go
- hooks_user_marker.go
- import.go
- index.go
- init.go
- init_marker_urls.go
- integrate.go
- login.go
- logout.go
- main.go
- memory.go
- memory_distill.go
- memory_put.go
- murmur.go
- murmur_delete.go
- murmur_list.go
- murmur_status.go
- prime_marker.go
- prime_session_marker.go
- query.go
- redaction.go
- release_notes.go
- root.go
- session.go
- session_commit.go
- session_content.go
- session_export.go
- session_force_stop.go
- session_helpers.go
- session_hydrate.go
- session_lint.go
- session_list.go
- session_meta_helper.go
- session_migrate_lfs.go
- session_optimize_for_summary.go
- session_push_summary.go
- session_regenerate.go
- session_remove.go
- session_repair_meta_summary.go
- session_resummary.go
- session_resummary_batch.go
- session_score.go
- session_show.go
- session_start.go
- session_status.go
- session_stop.go
- session_token_optimize.go
- session_upload.go
- session_upload_cmd.go
- session_url.go
- session_validate.go
- session_view.go
- session_view_context.go
- session_view_html.go
- session_view_text.go
- status.go
- sync.go
- team_discovery.go
- teams.go
- thanks.go
- uninstall.go
- uninstall_agent_files.go
- upgrade.go
- url_fallback.go
- version.go
- version_cache.go
- view.go