feat(sdk): type guard all the things! (#108)

## What

<!-- Brief description of the changes -->
Adds additional type guards

## Why

<!-- Motivation and context -->

## PR title format

<!--
PR titles must follow Conventional Commits: <type>(<scope>):
<description>

Types: feat | fix | docs | style | refactor | perf | test | build | ci |
chore | revert
  Scopes: sdk | acp | claude | examples | deps | project
  
  Examples:
    feat(sdk): add reconnect support
    fix(acp): handle timeout on long-running tasks
    docs(claude): update connection examples
    deps(sdk): bump @runloop/api-client to 1.5.0
    ci(project): add PR title validation workflow
-->

## Checklist

- [ ] PR title follows `<type>(<scope>): <description>` format (see
above)
- [ ] `bun run check` passes (lint + format)
- [ ] `bun run build` passes
- [ ] `bun run test` passes
- [ ] SDK documentation updated (if applicable)

Author: james-rl

sdk/src/acp/axon-stream.ts

@@ -5,6 +5,7 @@ import type { Axon } from "@runloop/api-client/sdk";
 import { isSystemError, SystemError } from "../shared/errors/system-error.js";
 import { makeDefaultOnError } from "../shared/logging.js";
 import { isFromAgent, isFromUser } from "../shared/origin-guards.js";
+import { getJsonRpcId, isNonNullObject } from "../shared/structural-guards.js";
 import type { LogFn } from "../shared/types.js";
 import type { AxonStreamOptions } from "./types.js";
 
@@ -348,8 +349,9 @@ function axonEventToJsonRpc(
   // entry so subsequent calls to the same method aren't rejected as duplicates.
   if (isJsonRpcMessage(parsed)) {
     if ("result" in parsed || "error" in parsed) {
+      const parsedId = getJsonRpcId(parsed);
       for (const [method, id] of pendingRequests) {
-        if (id === (parsed as Record<string, unknown>).id) {
+        if (id === parsedId) {
           pendingRequests.delete(method);
           break;
         }
@@ -546,9 +548,6 @@ function isAgentMethod(eventType: string): boolean {
  * @returns `true` if `obj` looks like a JSON-RPC 2.0 message.
  */
 function isJsonRpcMessage(obj: unknown): obj is AnyMessage {
-  if (typeof obj !== "object" || obj === null) return false;
-  const record = obj as Record<string, unknown>;
-  return (
-    record.jsonrpc === "2.0" && ("method" in record || "result" in record || "error" in record)
-  );
+  if (!isNonNullObject(obj)) return false;
+  return obj.jsonrpc === "2.0" && ("method" in obj || "result" in obj || "error" in obj);
 }

sdk/src/acp/index.ts

@@ -62,7 +62,12 @@ export {
   ClientSideConnection,
   PROTOCOL_VERSION,
 } from "@agentclientprotocol/sdk";
-export { isFromAgent, isFromUser } from "../shared/origin-guards.js";
+export {
+  type AgentOriginEvent,
+  isFromAgent,
+  isFromUser,
+  type UserOriginEvent,
+} from "../shared/origin-guards.js";
 export { tryParseSystemEvent, tryParseTimelinePayload } from "../shared/timeline.js";
 export type {
   AxonEventListener,

sdk/src/claude/classify-claude-axon-event.ts

@@ -1,3 +1,4 @@
+import { hasStringType } from "../shared/structural-guards.js";
 import { createClassifier } from "../shared/timeline.js";
 import { MESSAGE_TYPE_TO_EVENT_TYPE } from "./transport.js";
 import type { ClaudeProtocolTimelineEvent } from "./types.js";
@@ -30,7 +31,7 @@ export const classifyClaudeAxonEvent = createClassifier<ClaudeProtocolTimelineEv
   label: "classifyClaudeAxonEvent",
   isProtocolEventType: isClaudeProtocolEventType,
   toProtocolEvent: (data, ev) => {
-    if (data && typeof data === "object" && "type" in data) {
+    if (hasStringType(data)) {
       return {
         kind: "claude_protocol",
         eventType: ev.event_type,

sdk/src/claude/index.ts

@@ -64,7 +64,12 @@ export type {
   SDKUserMessage,
   SDKUserMessageReplay,
 } from "@anthropic-ai/claude-agent-sdk";
-export { isFromAgent, isFromUser } from "../shared/origin-guards.js";
+export {
+  type AgentOriginEvent,
+  isFromAgent,
+  isFromUser,
+  type UserOriginEvent,
+} from "../shared/origin-guards.js";
 export { tryParseSystemEvent, tryParseTimelinePayload } from "../shared/timeline.js";
 export type {
   AxonEventListener,
@@ -122,6 +127,8 @@ export {
 export {
   AxonTransport,
   type AxonTransportOptions,
+  type ControlRequestEvent,
+  type ControlResponseEvent,
   isControlRequest,
   isControlResponse,
   type Transport,

sdk/src/claude/timeline-event-guards.ts

@@ -23,6 +23,7 @@
  * @module
  */
 
+import { isTextContentBlock } from "../shared/structural-guards.js";
 import type {
   ClaudeAssistantTimelineEvent,
   ClaudeControlRequestTimelineEvent,
@@ -116,16 +117,7 @@ export function isClaudeAssistantTextEvent(
   if (!Array.isArray(content)) {
     return false;
   }
-  return content.some(
-    (block) =>
-      block != null &&
-      typeof block === "object" &&
-      "type" in block &&
-      block.type === "text" &&
-      "text" in block &&
-      typeof block.text === "string" &&
-      block.text.trim().length > 0,
-  );
+  return content.some((block) => isTextContentBlock(block) && block.text.trim().length > 0);
 }
 
 /**

sdk/src/claude/transport.ts

@@ -14,6 +14,7 @@ import type { Stream } from "@runloop/api-client/streaming";
 import { isSystemError, SystemError } from "../shared/errors/system-error.js";
 import { makeLogger } from "../shared/logging.js";
 import { isFromAgent, isFromUser } from "../shared/origin-guards.js";
+import { getRequestId, isNonNullObject } from "../shared/structural-guards.js";
 import type { LogFn } from "../shared/types.js";
 import type { WireData } from "./types.js";
 
@@ -22,7 +23,19 @@ import type { WireData } from "./types.js";
 // ---------------------------------------------------------------------------
 
 /**
- * Returns `true` if the event is a `control_request` (agent requesting permission).
+ * AxonEventView narrowed to `control_request` event type.
+ * @category Transport
+ */
+export type ControlRequestEvent = AxonEventView & { event_type: "control_request" };
+
+/**
+ * AxonEventView narrowed to `control_response` event type.
+ * @category Transport
+ */
+export type ControlResponseEvent = AxonEventView & { event_type: "control_response" };
+
+/**
+ * Type guard that narrows an event to `control_request`.
  *
  * This checks the event *type* only; pair with {@link isFromAgent} to confirm
  * direction (control requests originate from the agent).
@@ -31,12 +44,12 @@ import type { WireData } from "./types.js";
  * @returns `true` if `event_type === "control_request"`.
  * @category Transport
  */
-export function isControlRequest(event: AxonEventView): boolean {
+export function isControlRequest(event: AxonEventView): event is ControlRequestEvent {
   return event.event_type === "control_request";
 }
 
 /**
- * Returns `true` if the event is a `control_response` (client responding to permission request).
+ * Type guard that narrows an event to `control_response`.
  *
  * This checks the event *type* only; pair with {@link isFromUser} to confirm
  * direction (control responses originate from the client).
@@ -45,7 +58,7 @@ export function isControlRequest(event: AxonEventView): boolean {
  * @returns `true` if `event_type === "control_response"`.
  * @category Transport
  */
-export function isControlResponse(event: AxonEventView): boolean {
+export function isControlResponse(event: AxonEventView): event is ControlResponseEvent {
   return event.event_type === "control_response";
 }
 
@@ -281,10 +294,10 @@ export class AxonTransport implements Transport {
           if (event.payload != null) {
             try {
               const parsed = JSON.parse(event.payload);
-              if (parsed != null && typeof parsed === "object") {
-                const requestId: string | undefined = parsed.request_id;
+              if (isNonNullObject(parsed)) {
+                const requestId = getRequestId(parsed);
                 if (requestId) {
-                  replayBuffer.set(requestId, parsed);
+                  replayBuffer.set(requestId, parsed as WireData);
                   this.log("read", `#${eventCount} REPLAY buffered control_request ${requestId}`);
                 }
               }
@@ -297,8 +310,8 @@ export class AxonTransport implements Transport {
           if (event.payload != null) {
             try {
               const parsed = JSON.parse(event.payload);
-              const response = parsed?.response;
-              const requestId: string | undefined = response?.request_id;
+              const response = isNonNullObject(parsed) ? parsed.response : undefined;
+              const requestId = getRequestId(response);
               if (requestId && replayBuffer.has(requestId)) {
                 replayBuffer.delete(requestId);
                 this.log("read", `#${eventCount} REPLAY resolved control_request ${requestId}`);
@@ -344,11 +357,11 @@ export class AxonTransport implements Transport {
         }
         try {
           const parsed = JSON.parse(event.payload);
-          if (parsed == null || typeof parsed !== "object") {
+          if (!isNonNullObject(parsed)) {
             this.log("read", `#${eventCount} skipping non-object payload`);
             continue;
           }
-          yield parsed;
+          yield parsed as WireData;
         } catch (err) {
           this.log(
             "read",

sdk/src/shared/index.ts

@@ -21,8 +21,23 @@ export { SystemError, type SystemErrorEventInfo } from "./errors/system-error.js
 export { runDisconnectHook } from "./lifecycle.js";
 export { ListenerSet } from "./listener-set.js";
 export { makeDefaultOnError, makeLogger } from "./logging.js";
-export { isFromAgent, isFromUser } from "./origin-guards.js";
+export {
+  type AgentOriginEvent,
+  isFromAgent,
+  isFromUser,
+  type UserOriginEvent,
+} from "./origin-guards.js";
 export { getLastSequence } from "./replay.js";
+export {
+  getJsonRpcId,
+  getRequestId,
+  getStringProp,
+  hasJsonRpcId,
+  hasRequestId,
+  hasStringType,
+  isNonNullObject,
+  isTextContentBlock,
+} from "./structural-guards.js";
 export {
   type ClassifyConfig,
   createClassifier,
@@ -51,7 +66,6 @@ export {
   isUnknownTimelineEvent,
 } from "./timeline-event-guards.js";
 export { timelineEventGenerator } from "./timeline-generator.js";
-/** @category Types */
 /** @category Timeline */
 export type {
   AgentErrorEvent,

sdk/src/shared/origin-guards.ts

@@ -34,6 +34,32 @@ import type { BaseTimelineEvent } from "./types.js";
  */
 type HasOrigin = AxonEventView | BaseTimelineEvent;
 
+/**
+ * Narrows an event to agent origin.
+ *
+ * - For `AxonEventView` (default): narrows the top-level `origin` field.
+ * - For `BaseTimelineEvent` subtypes: narrows `axonEvent.origin` instead,
+ *   since timeline events carry the origin on their nested `axonEvent`.
+ *
+ * @category Origin
+ */
+export type AgentOriginEvent<T extends HasOrigin = AxonEventView> = T extends BaseTimelineEvent
+  ? T & { axonEvent: { origin: "AGENT_EVENT" } }
+  : T & { origin: "AGENT_EVENT" };
+
+/**
+ * Narrows an event to user origin.
+ *
+ * - For `AxonEventView` (default): narrows the top-level `origin` field.
+ * - For `BaseTimelineEvent` subtypes: narrows `axonEvent.origin` instead,
+ *   since timeline events carry the origin on their nested `axonEvent`.
+ *
+ * @category Origin
+ */
+export type UserOriginEvent<T extends HasOrigin = AxonEventView> = T extends BaseTimelineEvent
+  ? T & { axonEvent: { origin: "USER_EVENT" } }
+  : T & { origin: "USER_EVENT" };
+
 /**
  * Extracts the origin string from either an AxonEventView or a timeline event.
  */
@@ -42,27 +68,27 @@ function getOrigin(eventOrTimeline: HasOrigin): string {
 }
 
 /**
- * Returns `true` if the event originated from the agent.
+ * Type guard that narrows an event to agent origin.
  *
  * Works with both raw `AxonEventView` objects and timeline events.
  *
  * @param event - An AxonEventView or a timeline event containing one.
  * @returns `true` if `origin === "AGENT_EVENT"`.
  * @category Origin
  */
-export function isFromAgent(event: HasOrigin): boolean {
+export function isFromAgent<T extends HasOrigin>(event: T): event is AgentOriginEvent<T> {
   return getOrigin(event) === "AGENT_EVENT";
 }
 
 /**
- * Returns `true` if the event originated from the user/client.
+ * Type guard that narrows an event to user origin.
  *
  * Works with both raw `AxonEventView` objects and timeline events.
  *
  * @param event - An AxonEventView or a timeline event containing one.
  * @returns `true` if `origin === "USER_EVENT"`.
  * @category Origin
  */
-export function isFromUser(event: HasOrigin): boolean {
+export function isFromUser<T extends HasOrigin>(event: T): event is UserOriginEvent<T> {
   return getOrigin(event) === "USER_EVENT";
 }