@theway-ai/sdk 0.1.9

package/proto/events.proto

@@ -0,0 +1,87 @@
+// Event plane: unified snapshot/event stream envelope, the high-frequency
+// subagent / graph-engine event increments, and the EventService RPC surface.
+
+syntax = "proto3";
+package theway.grpc.v1;
+
+import "commands.proto";
+import "session.proto";
+
+// Unified envelope for StreamEvents / WebSocket frames.
+message StreamFrame {
+  oneof payload {
+    SessionSnapshot snapshot = 1; // connection start + full resync frames
+    StreamEvent event = 2; // high-frequency increment
+  }
+}
+
+message StreamEvent {
+  string session_id = 7;
+  oneof kind {
+    SubagentStarted subagent_started = 1;
+    SubagentOutput subagent_output = 2;
+    SubagentMetrics subagent_metrics = 3;
+    SubagentCompleted subagent_completed = 4;
+    NodeStatus node_status = 5;
+    RunStatus run_status = 6;
+  }
+}
+
+message SubagentStarted {
+  string id = 1;
+  string agent = 2;
+  string source = 3;
+  optional string run_id = 4;
+  optional string node_id = 5;
+}
+
+message SubagentOutput {
+  string id = 1;
+  string chunk = 2; // high-frequency, untruncated
+}
+
+message SubagentMetrics {
+  string id = 1;
+  double tps = 2;
+  double cps = 3;
+  uint64 chars = 4;
+  uint64 tokens_in = 5;
+  uint64 tokens_out = 6;
+  uint64 tools_called = 7;
+  uint32 turn = 8;
+}
+
+message SubagentCompleted {
+  string id = 1;
+  string status = 2;
+  optional string error = 3;
+  optional uint64 duration_ms = 4;
+  uint64 chars = 5;
+  uint64 tokens_in = 6;
+  uint64 tokens_out = 7;
+  uint64 tools_called = 8;
+}
+
+message NodeStatus {
+  string run_id = 1;
+  string node_id = 2;
+  string status = 3;
+  optional string error = 4;
+}
+
+message RunStatus {
+  string run_id = 1;
+  string status = 2;
+  optional string error = 3;
+}
+
+message StreamEventsRequest {
+  // Omitted = all sessions; set = only events for this session.
+  optional string session_id = 1;
+}
+
+service EventService {
+  // Snapshot/event stream (P0: snapshot frames; P2+: event increments).
+  // An optional session_id filters the stream to one session.
+  rpc StreamEvents(StreamEventsRequest) returns (stream StreamFrame);
+}

package/proto/extensions.proto

@@ -0,0 +1,99 @@
+// Runtime-extension domain: client-neutral status and serialized commands.
+
+syntax = "proto3";
+package theway.grpc.v1;
+
+import "commands.proto";
+
+message ExtensionSnapshot {
+  uint64 revision = 1;
+  bool reload_pending = 2;
+  repeated ExtensionCatalogEntry catalog = 3;
+  repeated ExtensionDiagnostic diagnostics = 4;
+  repeated ExtensionCommandDescriptor commands = 5;
+  repeated ExtensionContribution contributions = 6;
+}
+
+message ExtensionCatalogEntry {
+  string extension_id = 1;
+  string version = 2;
+  string source = 3;
+  string scope = 4;
+  int32 priority = 5;
+  string status = 6;
+  repeated string permissions = 7;
+  optional string reason_code = 8;
+}
+
+message ExtensionDiagnostic {
+  string extension_id = 1;
+  string code = 2;
+  string severity = 3;
+  string message = 4;
+  optional string session_id = 5;
+  optional string event = 6;
+  optional uint64 sequence = 7;
+  // JSON object containing only public details. Sensitive detail values are
+  // absent and their names appear in redacted_fields.
+  string details_json = 8;
+  repeated string redacted_fields = 9;
+}
+
+message ExtensionCommandDescriptor {
+  string extension_id = 1;
+  string name = 2;
+  string label = 3;
+  string description = 4;
+  string argument_schema_json = 5;
+}
+
+// Open envelope: clients skip unrecognized kind values without decoding
+// payload_json. This avoids a closed enum/oneof compatibility dependency.
+message ExtensionContribution {
+  string contribution_id = 1;
+  string extension_id = 2;
+  string scope = 3;
+  string kind = 4;
+  string payload_json = 5;
+}
+
+message InvokeExtensionCommandRequest {
+  string name = 1;
+  string arguments_json = 2;
+  bool has_interactive_client = 3;
+}
+
+message ExtensionCommandOutcome {
+  string status = 1;
+  optional string code = 2;
+  optional string message = 3;
+  optional string data_json = 4;
+}
+
+message ReloadExtensionsRequest {
+  bool cancel_active = 1;
+}
+
+message ReloadExtensionsResponse {
+  string status = 1;
+  uint64 revision = 2;
+}
+
+message DecideExtensionTrustRequest {
+  string subject = 1;
+  optional string extension_id = 2;
+  string decision = 3;
+  repeated string granted_permissions = 4;
+}
+
+message DecideExtensionTrustResponse {
+  bool accepted = 1;
+  ReloadExtensionsResponse reload = 2;
+}
+
+service ExtensionService {
+  rpc GetExtensions(Empty) returns (ExtensionSnapshot);
+  rpc InvokeCommand(InvokeExtensionCommandRequest) returns (ExtensionCommandOutcome);
+  rpc Reload(ReloadExtensionsRequest) returns (ReloadExtensionsResponse);
+  rpc DecideTrust(DecideExtensionTrustRequest) returns (DecideExtensionTrustResponse);
+}

package/proto/graph_engine.proto

@@ -0,0 +1,236 @@
+// 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;
+  string session_id = 4;
+}
+
+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;
+  string session_id = 2;
+}
+
+message GraphRetryRequest {
+  string run_id = 1;
+  optional string node_id = 2; // omitted = all failed/cancelled nodes
+  string session_id = 3;
+}
+
+message GraphRetryResponse {
+  repeated string reset_node_ids = 1;
+}
+
+message GraphSkipRequest {
+  string run_id = 1;
+  string node_id = 2;
+  string session_id = 3;
+}
+
+// Turn-level control for a running DAG node's subagent.
+message GraphNodeInterruptRequest {
+  string run_id = 1;
+  string node_id = 2;
+  string session_id = 3;
+}
+
+message GraphNodeSteerRequest {
+  string run_id = 1;
+  string node_id = 2;
+  string text = 3;
+  string session_id = 4;
+}
+
+message GraphSkipResponse {
+  bool skipped = 1;
+}
+
+// Checkpoints are organized by session: a session owns its runs
+// (DagRun.session_id), and `SessionSnapshot.graph_state.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;
+}
+
+// Node type in a session graph.
+enum SessionGraphNodeType {
+  SESSION_GRAPH_NODE_TYPE_UNSPECIFIED = 0;
+  SESSION_GRAPH_NODE_TYPE_SESSION = 1;
+  SESSION_GRAPH_NODE_TYPE_COLLAPSED = 2;
+}
+
+// A node in the session graph. Session nodes represent live sessions;
+// collapsed nodes represent archived sessions folded into another session.
+message SessionGraphNode {
+  string id = 1;
+  string session_id = 2;
+  SessionGraphNodeType type = 3;
+  string title = 4;
+  string summary = 5;
+  optional string parent_node_id = 6;
+  repeated string child_node_ids = 7;
+  optional string collapsed_session_id = 8;
+  optional string collapsed_at = 9; // RFC3339 / ISO-8601 with offset (UTC).
+  optional string created_at = 10;
+  optional string updated_at = 11;
+  uint32 message_count = 12;
+}
+
+// Detailed record for a session that has been collapsed into another session.
+message CollapsedSessionNode {
+  string node_id = 1;
+  string session_id = 2;
+  string title = 3;
+  string summary = 4;
+  uint32 message_count = 5;
+  optional string collapsed_at = 6; // RFC3339 / ISO-8601 with offset (UTC).
+  optional string collapsed_into_session_id = 7;
+  optional string collapsed_into_node_id = 8;
+  repeated string original_session_ids = 9;
+}
+
+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);
+}