@theway-ai/sdk 1.1.0

package/proto/graph_engine.proto

@@ -0,0 +1,193 @@
+// Graph engine domain: DAG/goal run state, subagent jobs, node output,
+// control, checkpoint/restore, run enumeration, and the GraphEngineService
+// RPC surface. Planning is agent-side; this surface observes and steers runs
+// created by the dag_plan / goal tools.
+
+syntax = "proto3";
+package theway.grpc.v1;
+
+import "commands.proto";
+
+message DagRunSnapshot {
+  string id = 1;
+  string name = 2;
+  string status = 3; // running/completed/failed/cancelled
+  bool fail_fast = 4;
+  uint32 max_concurrency = 5;
+  string direction = 6; // TD/LR
+  int64 created_at = 7;
+  optional int64 completed_at = 8;
+  optional string error = 9;
+  repeated DagNodeSnapshot nodes = 10;
+  string kind = 11; // "dag" | "goal" — goal runs are single-node self-loops (condition-terminated)
+}
+
+message DagNodeSnapshot {
+  string id = 1;
+  string agent = 2;
+  string status = 3; // pending/ready/running/succeeded/failed/skipped/cancelled
+  repeated string depends_on = 4;
+  optional string job_id = 5; // ↔ SubagentJobSnapshot.id
+  uint32 attempt = 6;
+  optional int64 started_at = 7;
+  optional int64 completed_at = 8;
+  optional string error = 9;
+  optional uint64 input_tokens = 10;
+  optional uint64 output_tokens = 11;
+  optional NodeResultSnapshot result = 12;
+  optional string output_tail = 13; // terminal output tail; full text via events/GetNodeOutput
+  optional string live_preview = 14; // live output while running
+}
+
+message NodeResultSnapshot {
+  bool success = 1;
+  optional string error = 2;
+  optional uint64 duration_ms = 3;
+  uint32 attempt = 4;
+  uint32 total_attempts = 5;
+}
+
+message SubagentJobSnapshot {
+  string id = 1;
+  string agent = 2; // general / explorer / executor-coder / ...
+  string source = 3; // task | dag
+  optional string run_id = 4;
+  optional string node_id = 5;
+  string status = 6; // running/succeeded/failed/cancelled
+  optional int64 started_at = 7;
+  optional int64 completed_at = 8;
+  optional uint64 duration_ms = 9;
+  uint32 attempt = 10;
+  uint32 total_attempts = 11;
+  optional uint64 input_tokens = 12;
+  optional uint64 output_tokens = 13;
+  optional string error = 14;
+  optional string output_tail = 15;
+  optional string live_preview = 16;
+  // graph mode metrics:
+  optional double tps = 17; // output tokens/sec (sliding window)
+  optional double cps = 18; // output chars/sec
+  optional uint64 chars = 19; // cumulative output chars
+  optional uint64 tools_called = 20; // cumulative tool calls
+  optional uint32 turn = 21; // completed turns
+}
+
+// Full output of a DAG node, fetched on demand with an offset (P3).
+message GetNodeOutputRequest {
+  string run_id = 1;
+  string node_id = 2;
+  uint64 offset = 3;
+}
+
+message GetNodeOutputResponse {
+  string text = 1; // fragment from offset
+  uint64 offset = 2; // start offset of this fragment
+  uint64 total = 3; // full length
+  bool truncated = 4; // server buffer capped
+  // Full conversation transcript (user prompts + assistant turns with tool
+  // calls + tool results) as a JSON array of serde_json::Value — the same
+  // shape the registry keeps in memory and on disk. "" when unavailable
+  // (e.g. unknown node). Optional so older clients keep working.
+  optional string messages_json = 5;
+  bool messages_truncated = 6; // transcript buffer was capped (oldest dropped)
+}
+
+enum GraphKind {
+  GRAPH_DAG = 0;
+  GRAPH_GOAL = 1;
+}
+
+message GraphCancelRequest {
+  string run_id = 1;
+}
+
+message GraphRetryRequest {
+  string run_id = 1;
+  optional string node_id = 2; // omitted = all failed/cancelled nodes
+}
+
+message GraphRetryResponse {
+  repeated string reset_node_ids = 1;
+}
+
+message GraphSkipRequest {
+  string run_id = 1;
+  string node_id = 2;
+}
+
+// Turn-level control for a running DAG node's subagent.
+message GraphNodeInterruptRequest {
+  string run_id = 1;
+  string node_id = 2;
+}
+
+message GraphNodeSteerRequest {
+  string run_id = 1;
+  string node_id = 2;
+  string text = 3;
+}
+
+message GraphSkipResponse {
+  bool skipped = 1;
+}
+
+// Checkpoints are organized by session: a session owns its runs
+// (DagRun.session_id), and `SessionState.dags` mounts the live graph status
+// under that session. Checkpoint exports one run or the session's whole graph
+// set as portable JSON snapshots; restore revives them back under the session.
+message GraphCheckpointRequest {
+  // Owning session. Omitted = the session this connection belongs to.
+  optional string session_id = 1;
+  // Omitted = every running run of the session; set to export a single run.
+  optional string run_id = 2;
+}
+
+message GraphCheckpointResponse {
+  string session_id = 1;
+  repeated GraphSnapshotEntry checkpoints = 2;
+  optional string error = 3;
+}
+
+message GraphSnapshotEntry {
+  GraphKind kind = 1;
+  string run_id = 2;
+  string snapshot = 3; // JSON (PersistedRun shape: definition, node states, progress)
+}
+
+// Restore: resume run(s) from GraphCheckpoint snapshots. Running runs are
+// revived with their ready nodes re-scheduled, and re-attached to the session.
+message GraphRestoreRequest {
+  string session_id = 1;
+  string snapshot = 2; // single GraphSnapshotEntry.snapshot (PersistedRun JSON)
+}
+
+message GraphRestoreResponse {
+  string run_id = 1;
+  optional string error = 2;
+}
+
+message GraphListRequest {
+  string session_id = 1;
+}
+
+message GraphListResponse {
+  repeated DagRunSnapshot runs = 1;
+}
+
+service GraphEngineService {
+  // Fetch a DAG node's full output from an offset (P3).
+  rpc GetNodeOutput(GetNodeOutputRequest) returns (GetNodeOutputResponse);
+  // Graph orchestration control (DAG + goal runs; planning is agent-side).
+  rpc GraphCancel(GraphCancelRequest) returns (CommandResult);
+  rpc GraphRetry(GraphRetryRequest) returns (GraphRetryResponse);
+  rpc GraphSkip(GraphSkipRequest) returns (GraphSkipResponse);
+  // Stop the node's in-flight turn (run ends unless steering was queued).
+  rpc GraphNodeInterrupt(GraphNodeInterruptRequest) returns (CommandResult);
+  // Queue a steering message injected at the node's next natural turn boundary.
+  rpc GraphNodeSteer(GraphNodeSteerRequest) returns (CommandResult);
+  // Checkpoint / restore (portable run snapshots for external persistence).
+  rpc GraphCheckpoint(GraphCheckpointRequest) returns (GraphCheckpointResponse);
+  rpc GraphRestore(GraphRestoreRequest) returns (GraphRestoreResponse);
+  // Enumerate one session's graph runs (DagRunSnapshot shape).
+  rpc GraphList(GraphListRequest) returns (GraphListResponse);
+}

package/proto/health.proto

@@ -0,0 +1,26 @@
+// Standard gRPC health checking protocol (grpc.health.v1), hand-written
+// equivalent of grpc/grpc's health.proto. Served alongside theway.grpc.v1 so
+// generic health probes (grpc_health_probe, load balancers, k8s-style checks)
+// work without importing the domain proto. See docs/PROTOCOL.md.
+
+syntax = "proto3";
+package grpc.health.v1;
+
+message HealthCheckRequest {
+  string service = 1;
+}
+
+message HealthCheckResponse {
+  enum ServingStatus {
+    UNKNOWN = 0;
+    SERVING = 1;
+    NOT_SERVING = 2;
+    SERVICE_UNKNOWN = 3;
+  }
+  ServingStatus status = 1;
+}
+
+service Health {
+  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
+  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
+}

package/proto/session.proto

@@ -0,0 +1,299 @@
+// Session domain: the full session state plane (snapshot, sidebar, feed,
+// model catalog, status), session resource messages
+// (list/create/switch/rename/delete), and the SessionService RPC surface.
+
+syntax = "proto3";
+package theway.grpc.v1;
+
+import "commands.proto";
+import "extensions.proto";
+import "graph_engine.proto";
+
+// Full session state (the structured form of the former WireSnapshot JSON).
+// Low-frequency, whole-replacement: GetState / stream snapshot frames.
+message SessionState {
+  string session_id = 1;
+  string model = 2;
+  repeated ProviderGroup model_catalog = 3;
+  string cwd = 4;
+  bool busy = 5;
+  uint32 queued_count = 6;
+  optional TriggerPollStatus latest_trigger_poll = 7;
+  optional GoalSnapshot goal = 8;
+  optional ControlPlanePromptSnapshot control_plane_prompt = 9;
+  SidebarSnapshot sidebar = 10;
+  repeated FeedBlock feed_blocks = 11;
+  repeated string feed_lines = 12;
+  // graph mode (P1/P2 fill these):
+  repeated DagRunSnapshot dags = 13;
+  repeated SubagentJobSnapshot subagents = 14;
+  // TUI display settings pushed from the daemon (read from config.toml).
+  optional uint32 tui_max_feed_lines = 15;
+  // Token usage + context window for the live session.
+  optional ContextUsage context_usage = 16;
+  // Absolute index of feed_lines[0] in the full transcript (issue #35):
+  // stream snapshots carry only rows appended since the last publish; the
+  // initial get_state snapshot carries everything (base 0).
+  uint64 feed_lines_base = 17;
+  // Incremental gRPC snapshot frames require this many blocks to already be
+  // present on the consumer. Zero denotes a full replacement frame.
+  uint64 feed_blocks_base = 18;
+  // Appends/replacements since feed_blocks_base. Full frames leave this empty.
+  repeated FeedBlockPatch feed_block_patches = 19;
+  // Runtime-extension status is additive; older clients ignore this field.
+  ExtensionSnapshot extensions = 20;
+}
+
+message FeedBlockPatch {
+  // index == consumer length appends; index < length replaces; index > length
+  // is a gap and requires a full GetState resync.
+  uint64 index = 1;
+  FeedBlock block = 2;
+}
+
+// Token usage for the current/last turn, plus the model's context window size.
+message ContextUsage {
+  uint64 input_tokens = 1;
+  uint64 output_tokens = 2;
+  uint64 cache_read_tokens = 3;
+  uint64 cache_write_tokens = 4;
+  uint64 total_tokens = 5;
+  uint32 context_window = 6;
+}
+
+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;
+    ToolBlock tool = 4;
+    ToolResultBlock tool_result = 5;
+    PlainBlock plain = 6;
+  }
+}
+
+message UserBlock {
+  string text = 1;
+  optional string timestamp = 2;
+}
+
+message AssistantBlock {
+  string text = 1;
+  optional string timestamp = 2;
+}
+
+message ThinkingBlock {
+  string text = 1;
+  optional string timestamp = 2;
+}
+
+message ToolBlock {
+  string name = 1;
+  string args = 2;
+  optional string timestamp = 3;
+}
+
+message ToolResultBlock {
+  repeated string lines = 1;
+  bool is_error = 2;
+  optional string timestamp = 3;
+}
+
+message PlainBlock {
+  string text = 1;
+  string level = 2; // "output" | "system" | "error" | "note" (serde snake_case variant names)
+  optional string timestamp = 3;
+}
+
+message SessionSummary {
+  string session_id = 1;
+  string name = 2;
+  string cwd = 3;
+  string model = 4;
+  string created_at = 5;
+  int64 last_activity_at = 6;
+  uint32 graph_count = 7;
+  uint32 active_graph_count = 8;
+  bool busy = 9;
+  optional string preview = 10;
+}
+
+message ListSessionsResponse {
+  repeated SessionSummary sessions = 1;
+  string current_session_id = 2;
+}
+
+message CreateSessionRequest {
+  optional string name = 1;
+}
+
+message CreateSessionResponse {
+  SessionSummary session = 1;
+}
+
+message SwitchSessionRequest {
+  string session_id = 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;
+}
+
+service SessionService {
+  // Full structured state (binary protobuf).
+  rpc GetState(Empty) returns (SessionState);
+  // Session resources: list (with current marker) / create / switch / 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 SwitchSession(SwitchSessionRequest) returns (CommandResult);
+  rpc RenameSession(RenameSessionRequest) returns (CommandResult);
+  rpc DeleteSession(DeleteSessionRequest) returns (DeleteSessionResponse);
+  // 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);
+}

package/proto/settings.proto

@@ -0,0 +1,73 @@
+// 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;
+
+  // 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);
+}