@theway-ai/sdk 0.1.9

package/proto/session.proto

@@ -0,0 +1,498 @@
+// Session domain: the full session state plane (snapshot, sidebar, feed,
+// model catalog, status), session resource messages
+// (list/create/rename/delete), and the SessionService RPC surface.
+
+syntax = "proto3";
+package theway.grpc.v1;
+
+import "commands.proto";
+import "extensions.proto";
+import "graph_engine.proto";
+
+// Incremental transcript patch: appends/replacements since a consumer cursor.
+message FeedBlockPatch {
+  // index == consumer length appends; index < length replaces; index > length
+  // is a gap and requires a full snapshot resync.
+  uint64 index = 1;
+  FeedBlock block = 2;
+}
+
+// Token usage for the current/last turn, plus the model's context window size.
+message ContextUsage {
+  uint64 cached_tokens = 1;
+  uint64 new_tokens = 2;
+  uint64 total_input_tokens = 3;
+  uint64 output_tokens = 4;
+  uint64 cache_write_tokens = 5;
+  optional double provider_cache_hit_rate = 6;
+  optional double prefix_cache_hit_rate = 7;
+  optional uint64 prefix_hit_tokens = 8;
+  uint32 context_window = 9;
+}
+
+message ProviderGroup {
+  string provider = 1;
+  bool has_credential = 2;
+  repeated ModelEntry models = 3;
+}
+
+message ModelEntry {
+  string id = 1;
+  string name = 2;
+}
+
+message TriggerPollStatus {
+  string checked_at = 1;
+  string trace_id = 2;
+  string source_label = 3;
+  string event_label = 4;
+  string summary = 5;
+}
+
+message GoalSnapshot {
+  string condition = 1;
+  string status = 2;
+  uint32 iterations = 3;
+  optional string last_reason = 4;
+}
+
+message ControlPlanePromptSnapshot {
+  string tool_name = 1;
+  string label = 2;
+  string reason = 3;
+  string args_hash = 4;
+  string payload = 5;
+}
+
+message SidebarSnapshot {
+  uint32 inbox_new = 1;
+  SkillsSnapshot skills = 2;
+  TriggersSnapshot triggers = 3;
+  CronSnapshot cron = 4;
+  McpSnapshot mcp = 5;
+  ToolsSnapshot tools = 6;
+  repeated string hooks = 7;
+  repeated string runtime = 8;
+  // Slash-prefixed file-command names (claude-code format, issue #37):
+  // discovered from .agents/commands + .claude/commands.
+  repeated string commands = 9;
+  // Daemon runtime revision, bumped by the `reload` agent tool; clients
+  // watch it to re-read local resources (e.g. ~/.theway/theme.toml).
+  uint64 runtime_revision = 10;
+}
+
+message SkillsSnapshot {
+  uint32 total = 1;
+  uint32 enabled = 2;
+  uint32 disabled = 3;
+  uint32 builtin = 4;
+  uint32 user = 5;
+  uint32 project = 6;
+  repeated SkillSnapshot items = 7;
+}
+
+message SkillSnapshot {
+  string name = 1;
+  string source = 2;
+  string file_path = 3;
+  bool enabled = 4;
+}
+
+message TriggersSnapshot {
+  uint32 total = 1;
+  uint32 enabled = 2;
+  uint32 disabled = 3;
+  repeated TriggerRuleSnapshot rules = 4;
+}
+
+message TriggerRuleSnapshot {
+  string id = 1;
+  string full_id = 2;
+  bool enabled = 3;
+  string mode = 4;
+  string condition = 5;
+  string action = 6;
+}
+
+message CronSnapshot {
+  uint32 total = 1;
+  uint32 enabled = 2;
+  uint32 disabled = 3;
+  repeated CronJobSnapshot jobs = 4;
+}
+
+message CronJobSnapshot {
+  string id = 1;
+  bool enabled = 2;
+  string schedule = 3;
+  string action = 4;
+  uint64 skipped_overlap_count = 5;
+  optional string last_error = 6;
+}
+
+message McpSnapshot {
+  uint32 servers = 1;
+  uint32 tools = 2;
+  uint32 notification_hooks = 3;
+  repeated string server_names = 4;
+  repeated string tool_names = 5;
+}
+
+message ToolsSnapshot {
+  uint32 total = 1;
+  repeated string names = 2;
+}
+
+// One renderable feed entry. oneof mirrors the serde tagged enum WireFeedBlock;
+// JSON channels keep serde shape until the protojson migration.
+message FeedBlock {
+  oneof kind {
+    UserBlock user = 1;
+    AssistantBlock assistant = 2;
+    ThinkingBlock thinking = 3;
+    ToolResultBlock tool_result = 5;
+    PlainBlock plain = 6;
+    ToolCallBlock tool_call = 7;
+    ErrorBlock error = 8;
+  }
+}
+
+message UserBlock {
+  string text = 1;
+  optional string timestamp = 2; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+}
+
+message AssistantBlock {
+  string text = 1;
+  optional string timestamp = 2; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+}
+
+message ThinkingBlock {
+  string text = 1;
+  optional string timestamp = 2; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+}
+
+message ToolCallBlock {
+  string name = 1;
+  string args = 2;
+  optional string metadata = 3; // Optional tool-call metadata (JSON string).
+  optional string timestamp = 4; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+}
+
+message ErrorBlock {
+  string message = 1;
+  optional string code = 2;
+  bool recoverable = 3;
+  optional string timestamp = 4; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+}
+
+message ToolResultBlock {
+  repeated string lines = 1;
+  bool is_error = 2;
+  optional string timestamp = 3; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+}
+
+message PlainBlock {
+  string text = 1;
+  string level = 2; // "output" | "system" | "error" | "note" (serde snake_case variant names)
+  optional string timestamp = 3; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+}
+
+message SessionSummary {
+  // Canonical session id. New clients should use this field; `session_id`
+  // remains as a deprecated alias for compatibility with older consumers.
+  string id = 13;
+  // Compatibility alias; new clients should read `id`.
+  string session_id = 1;
+  string name = 2;
+  string cwd = 3;
+  string model = 4;
+  string created_at = 5; // RFC3339 / ISO-8601 with offset (UTC).
+  int64 last_activity_at = 6; // Deprecated epoch milliseconds; use last_activity_at_rfc3339.
+  uint32 graph_count = 7;
+  uint32 active_graph_count = 8;
+  bool busy = 9;
+  optional string preview = 10;
+  map<string, string> metadata = 11;
+  optional string last_activity_at_rfc3339 = 12; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+  string tree_prefix = 14; // Pi-style tree prefix (`├─ ` / `└─ ` / `│ `) for fork-lineage display.
+}
+
+// Thinking levels supported by the runtime.
+enum ThinkingLevel {
+  THINKING_LEVEL_UNSPECIFIED = 0;
+  THINKING_LEVEL_OFF = 1;
+  THINKING_LEVEL_MINIMAL = 2;
+  THINKING_LEVEL_LOW = 3;
+  THINKING_LEVEL_MEDIUM = 4;
+  THINKING_LEVEL_HIGH = 5;
+  THINKING_LEVEL_XHIGH = 6;
+}
+
+// A resolved model reference in a session runtime.
+message ModelRef {
+  string provider = 1;
+  string model = 2;
+  optional string base_url = 3;
+}
+
+// Static/dynamic session identity and display metadata.
+message SessionInfo {
+  string id = 1;
+  string name = 2;
+  string cwd = 3;
+  string created_at = 4; // RFC3339 / ISO-8601 with offset (UTC).
+  int64 last_activity_at = 5; // Deprecated epoch milliseconds.
+  optional string last_activity_at_rfc3339 = 6; // RFC3339 / ISO-8601 with offset (UTC), null when absent.
+  bool busy = 7;
+  optional string preview = 8;
+  map<string, string> metadata = 9;
+  uint32 graph_count = 10;
+  uint32 active_graph_count = 11;
+  uint32 queued_count = 12;
+  SidebarSnapshot sidebar = 13;
+}
+
+// Live runtime configuration and model/context metadata.
+message SessionRuntime {
+  ModelRef model = 1;
+  ThinkingLevel thinking_level = 2;
+  repeated ThinkingLevel supported_thinking_levels = 3;
+  optional ContextUsage context_usage = 4;
+  optional ContextUsage session_context_usage = 5;
+  optional uint32 tui_max_feed_lines = 6;
+  repeated ProviderGroup model_catalog = 7;
+  optional TriggerPollStatus latest_trigger_poll = 8;
+  optional GoalSnapshot goal = 9;
+  optional ControlPlanePromptSnapshot control_plane_prompt = 10;
+  ExtensionSnapshot extensions = 11;
+  // Full rendered system context for the next request (base prompt + skills +
+  // tool inventory + working directory + memory + lineage). Mirrors the
+  // request/header epoch snapshot in deepseek-harness session logs.
+  string system_context = 12;
+}
+
+// Transcript plane of a session snapshot.
+message SessionFeed {
+  repeated FeedBlock blocks = 1;
+  repeated string lines = 2;
+  uint64 blocks_base = 3;
+  uint64 lines_base = 4;
+  repeated FeedBlockPatch block_patches = 5;
+}
+
+// Graph-mode state mounted under a session snapshot.
+message SessionGraphState {
+  repeated DagRunSnapshot dags = 1;
+  repeated SubagentJobSnapshot subagents = 2;
+  repeated SessionGraphNode nodes = 3;
+  optional string active_node_id = 4;
+}
+
+// Session lineage for fork/collapse ancestry.
+message SessionLineage {
+  optional string parent_session_id = 1;
+  optional string root_session_id = 2;
+  repeated string ancestor_session_ids = 3;
+  repeated string child_session_ids = 4;
+  optional string collapsed_from_session_id = 5;
+  optional string collapsed_into_session_id = 6;
+}
+
+// Full structured session snapshot: the single-version authoritative current
+// state shape served by GetSnapshot and StreamEvents snapshot frames.
+message SessionSnapshot {
+  string session_id = 1;
+  SessionInfo info = 2;
+  SessionRuntime runtime = 3;
+  SessionFeed feed = 4;
+  SessionGraphState graph_state = 5;
+  SessionLineage lineage = 6;
+}
+
+// Cursor-paginated read of the session's full message history. Entries are
+// addressed by storage entry id; `before_entry_id` returns the page of
+// message blocks strictly older than that entry.
+message ListSessionMessagesRequest {
+  string session_id = 1;
+  // Omitted = newest page of the active branch.
+  optional string before_entry_id = 2;
+  // Page size; server caps at 500.
+  uint32 limit = 3;
+}
+
+message SessionMessagePage {
+  string session_id = 1;
+  // Oldest → newest within the page.
+  repeated FeedBlock blocks = 2;
+  // Entry id of the oldest message in this page; empty when no older page.
+  optional string next_before_entry_id = 3;
+  bool has_more = 4;
+  // Total message count on the active branch.
+  uint64 total = 5;
+}
+
+// Collapse a session into a graph node, optionally under another session.
+message CollapseSessionRequest {
+  string session_id = 1;
+  optional string into_session_id = 2;
+  optional string title = 3;
+  optional string summary = 4;
+}
+
+message CollapseSessionResponse {
+  string session_id = 1;
+  SessionGraphNode node = 2;
+  CollapsedSessionNode collapsed = 3;
+}
+
+message GetSessionGraphNodeRequest {
+  string session_id = 1;
+  string node_id = 2;
+}
+
+message GetSessionGraphNodeResponse {
+  SessionGraphNode node = 1;
+}
+
+message ListSessionGraphNodeMessagesRequest {
+  string session_id = 1;
+  string node_id = 2;
+  uint32 offset = 3;
+  uint32 limit = 4;
+}
+
+message ListSessionGraphNodeMessagesResponse {
+  repeated FeedBlock blocks = 1;
+}
+
+message StreamSessionGraphNodeRequest {
+  string session_id = 1;
+  string node_id = 2;
+}
+
+// Streaming frame for node changes and message appends.
+message SessionGraphNodeStreamFrame {
+  oneof payload {
+    SessionGraphNode node = 1;
+    FeedBlock block = 2;
+  }
+}
+
+message SessionStateRequest {
+  string session_id = 1;
+}
+
+message UpdateSessionMetadataRequest {
+  string session_id = 1;
+  map<string, string> metadata = 2;
+}
+
+message ListSessionsResponse {
+  repeated SessionSummary sessions = 1;
+  string current_session_id = 2;
+}
+
+message CreateSessionRequest {
+  optional string name = 1;
+  optional string session_id = 2;
+  map<string, string> metadata = 3;
+}
+
+message CreateSessionResponse {
+  SessionSummary session = 1;
+}
+
+message RenameSessionRequest {
+  string session_id = 1;
+  string name = 2;
+}
+
+message DeleteSessionRequest {
+  string session_id = 1;
+}
+
+message DeleteSessionResponse {
+  // Non-empty = deletion refused, these graphs are still running.
+  repeated string running_run_ids = 1;
+}
+
+// Daemon path context (issue #68): home / base / work_dir are fixed at daemon
+// startup; skills_dirs reflects the current skill search directories and is
+// the only mutable part (see SetSkillDirs).
+message PathContext {
+  string home = 1;
+  string base = 2;
+  string work_dir = 3;
+  repeated string skills_dirs = 4;
+}
+
+message SetSkillDirsRequest {
+  repeated string dirs = 1;
+}
+
+// Session activation (issue #26): explicit client key and optional runtime.
+// Runtime is a singular message so its presence remains observable.
+message SessionRuntimeContext {
+  string work_dir = 1;
+  optional string provider = 2;
+  optional string model = 3;
+  optional string base_url = 4;
+  optional bool thinking = 5;
+}
+
+message ActivateSessionRequest {
+  optional string session_id = 1;
+  string client_key = 2;
+  optional string name = 3;
+  SessionRuntimeContext runtime = 4;
+}
+
+message ActivateSessionResponse {
+  SessionSummary session = 1;
+  bool created = 2;
+}
+
+message SetCredentialRequest {
+  string session_id = 1;
+  string provider = 2;
+  bytes secret = 3;
+}
+
+message ClearCredentialRequest {
+  string session_id = 1;
+  optional string provider = 2;
+}
+
+service SessionService {
+  // Full nested session snapshot: the single authoritative current snapshot.
+  rpc GetSnapshot(SessionStateRequest) returns (SessionSnapshot);
+  // Cursor-paginated full message history on the session's active branch.
+  rpc ListSessionMessages(ListSessionMessagesRequest) returns (SessionMessagePage);
+  // Collapse a session into a graph node (session-snapshot-collapse).
+  rpc CollapseSession(CollapseSessionRequest) returns (CollapseSessionResponse);
+  rpc GetSessionGraphNode(GetSessionGraphNodeRequest) returns (GetSessionGraphNodeResponse);
+  rpc ListSessionGraphNodeMessages(ListSessionGraphNodeMessagesRequest) returns (ListSessionGraphNodeMessagesResponse);
+  rpc StreamSessionGraphNode(StreamSessionGraphNodeRequest) returns (stream SessionGraphNodeStreamFrame);
+  // Session resources: list (with current marker) / create / rename /
+  // delete. DeleteSession reports the offending run ids when refused because
+  // the session still has running graphs.
+  rpc ListSessions(Empty) returns (ListSessionsResponse);
+  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
+  rpc RenameSession(RenameSessionRequest) returns (CommandResult);
+  rpc DeleteSession(DeleteSessionRequest) returns (DeleteSessionResponse);
+  // Update arbitrary session metadata KV (opaque to thewayd).
+  rpc UpdateSessionMetadata(UpdateSessionMetadataRequest) returns (CommandResult);
+  // Daemon path context (issue #68): home/base/work_dir plus the current
+  // skill search directories.
+  rpc GetPathContext(Empty) returns (PathContext);
+  // Replace the extra skill directories dynamically; the command is queued
+  // into the event loop, which applies it authoritatively (hot-reload).
+  // `accepted` = the command was queued.
+  rpc SetSkillDirs(SetSkillDirsRequest) returns (CommandResult);
+  // Session activation and credentials (issue #26): activate/resume a session
+  // and manage provider credentials without echoing secrets.
+  rpc ActivateSession(ActivateSessionRequest) returns (ActivateSessionResponse);
+  rpc SetCredential(SetCredentialRequest) returns (CommandResult);
+  rpc ClearCredential(ClearCredentialRequest) returns (CommandResult);
+}

package/proto/settings.proto

@@ -0,0 +1,79 @@
+// Settings domain (issue #72): the daemon configuration surface. Controllers
+// read the daemon's current configuration view (GetConfig) and push partial
+// updates (SetConfig / Configure) that the serialized event loop applies
+// authoritatively.
+
+syntax = "proto3";
+package theway.grpc.v1;
+
+import "commands.proto";
+
+// Daemon configuration snapshot / partial update (issue #72).
+//
+// Update semantics: a present `optional` field replaces the daemon's current
+// value; an absent one keeps it. Non-empty repeated values replace lists.
+// `clear_fields` explicitly clears optional or repeated fields, avoiding
+// proto3's absent-vs-empty ambiguity. When a field is both cleared and set in
+// one request, the set value wins.
+//
+// Covered areas: model selection (provider / model / base_url / thinking),
+// skills (builtin_skills / skills_dirs), triggers (trigger_poll_secs), and
+// TUI display (tui_max_feed_lines). Further config areas (relay,
+// orchestrator, hooks, cron, ...) gain fields here in later phases; field
+// numbers are append-only.
+message DaemonConfig {
+  // ── model selection ──
+  optional string provider = 1;
+  optional string model = 2;
+  // Custom provider endpoint URL.
+  optional string base_url = 3;
+  // Extended-thinking toggle.
+  optional bool thinking = 4;
+
+  // ── skills ──
+  // Enabled builtin skill names.
+  repeated string builtin_skills = 5;
+  // Extra skill search directories (mirrors PathContext.skills_dirs).
+  repeated string skills_dirs = 6;
+
+  // ── triggers ──
+  optional uint32 trigger_poll_secs = 7;
+
+  // ── tui ──
+  optional uint32 tui_max_feed_lines = 8;
+
+  // ── controller tool endpoint (issue #77) ──
+  // Address of the controller's ToolService server (host:port). When set, the
+  // daemon forwards file/process operations to this endpoint instead of
+  // executing them locally.
+  optional string tool_service_addr = 9;
+
+  // ── controller storage endpoint (issue #85) ──
+  // Address of the controller's StorageService server (host:port). When set,
+  // the daemon uses controller-backed runtime storage (sessions, DAG runs,
+  // trigger rules, cron jobs) over RPC instead of local storage directly.
+  optional string storage_service_addr = 10;
+
+  // ── thinking level (persisted last-choice default) ──
+  // Full thinking level string ("off" | "minimal" | "low" | "medium" |
+  // "high" | "xhigh"). Finer-grained than the `thinking` toggle; the toggle
+  // stays for legacy compatibility.
+  optional string thinking_level = 12;
+
+  // Field names to clear before applying values present in this message.
+  // Unknown names make the daemon reject the patch without partial changes.
+  repeated string clear_fields = 11;
+}
+
+service SettingsService {
+  // Current daemon configuration view: only values successfully applied by
+  // the serialized daemon event loop. `clear_fields` is empty in snapshots.
+  rpc GetConfig(Empty) returns (DaemonConfig);
+  // Push a partial configuration update. The command is queued into the
+  // serialized event loop, which applies it authoritatively;
+  // `accepted` = the command was queued.
+  rpc SetConfig(DaemonConfig) returns (CommandResult);
+  // Same operation as SetConfig; kept as a distinct method name so the
+  // JSON-RPC / WS / MCP surfaces can align on a `configure` verb.
+  rpc Configure(DaemonConfig) returns (CommandResult);
+}

package/proto/state.proto

@@ -0,0 +1,130 @@
+// Runtime state externalization domain (issue #84): the StorageService RPC
+// contract for the daemon's persistent runtime state. This is the transport
+// twin of the daemon-side RuntimeStorage seam (#79/#80): a controller/storage
+// side can list/create/rename/delete sessions, persist and reload DAG run
+// snapshots, and back up trigger rules and cron jobs without coupling to the
+// local filesystem/SQLite layout.
+//
+// Session methods mirror SessionService so external storage can drive the same
+// resource lifecycle; DAG/trigger/cron methods carry the serde wire twins from
+// `crate::wire` and are implemented by a StorageOps handler in the daemon.
+
+syntax = "proto3";
+package theway.grpc.v1;
+
+import "commands.proto";
+import "session.proto";
+
+// One persisted DAG run. `snapshot` is the portable JSON `PersistedRun` shape
+// used by GraphEngineService checkpoint/restore, so storage backends treat DAG
+// state as opaque JSON (definition + node progress).
+message StoredDagRun {
+  string session_id = 1;
+  string run_id = 2;
+  string snapshot = 3;
+}
+
+message SaveDagRunRequest {
+  string session_id = 1;
+  string run_id = 2;
+  string snapshot = 3;
+}
+
+message SaveDagRunResponse {
+  bool saved = 1;
+}
+
+message LoadDagRunsRequest {
+  string session_id = 1;
+  // Omitted = load every stored run for the session; set = load one run.
+  optional string run_id = 2;
+}
+
+message LoadDagRunsResponse {
+  repeated StoredDagRun runs = 1;
+}
+
+// Session-scoped dynamic trigger rule, persisted in the sidecar format
+// (`triggers.json`) but exposed as a portable storage contract.
+message StoredTriggerRule {
+  string id = 1;
+  string condition = 2;
+  string action = 3;
+  bool enabled = 4;
+  bool fire_once = 5;
+  optional string fired_at = 6; // RFC3339, when the rule has fired
+  bool promote_to_chat = 7;
+  string created_at = 8; // RFC3339
+}
+
+message SaveTriggerRulesRequest {
+  string session_id = 1;
+  repeated StoredTriggerRule rules = 2;
+}
+
+message SaveTriggerRulesResponse {
+  uint32 count = 1;
+}
+
+message LoadTriggerRulesRequest {
+  string session_id = 1;
+}
+
+message LoadTriggerRulesResponse {
+  repeated StoredTriggerRule rules = 1;
+}
+
+// Session-scoped cron job, persisted in the sidecar format (`cron.toml`) but
+// exposed as a portable storage contract.
+message StoredCronJob {
+  string id = 1;
+  string schedule = 2; // standard 5-field cron expression
+  string action = 3;
+  bool enabled = 4;
+  optional string running_trace_id = 5;
+  optional string last_due_at = 6; // RFC3339
+  optional string last_fired_at = 7; // RFC3339
+  optional string last_completed_at = 8; // RFC3339
+  optional string last_error = 9;
+  uint64 skipped_overlap_count = 10;
+  bool stateful = 11;
+  string created_at = 12; // RFC3339
+}
+
+message SaveCronJobsRequest {
+  string session_id = 1;
+  repeated StoredCronJob jobs = 2;
+}
+
+message SaveCronJobsResponse {
+  uint32 count = 1;
+}
+
+message LoadCronJobsRequest {
+  string session_id = 1;
+}
+
+message LoadCronJobsResponse {
+  repeated StoredCronJob jobs = 1;
+}
+
+service StorageService {
+  // Session resources (mirror SessionService).
+  rpc ListSessions(Empty) returns (ListSessionsResponse);
+  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
+  rpc RenameSession(RenameSessionRequest) returns (CommandResult);
+  rpc DeleteSession(DeleteSessionRequest) returns (DeleteSessionResponse);
+  rpc UpdateSessionMetadata(UpdateSessionMetadataRequest) returns (CommandResult);
+
+  // DAG run persistence.
+  rpc SaveDagRun(SaveDagRunRequest) returns (SaveDagRunResponse);
+  rpc LoadDagRuns(LoadDagRunsRequest) returns (LoadDagRunsResponse);
+
+  // Trigger rules persistence.
+  rpc SaveTriggerRules(SaveTriggerRulesRequest) returns (SaveTriggerRulesResponse);
+  rpc LoadTriggerRules(LoadTriggerRulesRequest) returns (LoadTriggerRulesResponse);
+
+  // Cron jobs persistence.
+  rpc SaveCronJobs(SaveCronJobsRequest) returns (SaveCronJobsResponse);
+  rpc LoadCronJobs(LoadCronJobsRequest) returns (LoadCronJobsResponse);
+}