@shogo-ai/core 1.4.1

package/dist/instrumentation.d.cts

@@ -0,0 +1,43 @@
+import { Span } from '@opentelemetry/api';
+
+/**
+ * OpenTelemetry tracing setup for Shogo runtime services.
+ *
+ * Wires a `NodeSDK` with an OTLP HTTP trace exporter pointed at
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`, optionally authenticated via
+ * `SIGNOZ_INGESTION_KEY`. In production / staging, spans are batched
+ * before flush; in development a `SimpleSpanProcessor` flushes
+ * eagerly so traces are visible immediately.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT.
+ * The OpenTelemetry packages are optional `peerDependencies` of the SDK
+ * — only consumers that actually call `initInstrumentation` need them
+ * installed.
+ *
+ * @example
+ *   import { initInstrumentation, traceOperation, shutdownInstrumentation }
+ *     from '@shogo-ai/sdk/instrumentation'
+ *
+ *   initInstrumentation({ serviceName: 'my-api', serviceVersion: '1.0.0' })
+ *
+ *   await traceOperation('my-api', 'cold-start', { region: 'us-west' }, async (span) => {
+ *     // ... boot work ...
+ *     span.setAttribute('warm-pool-size', 4)
+ *   })
+ *
+ *   process.on('SIGTERM', () => shutdownInstrumentation())
+ */
+
+interface InstrumentationConfig {
+    serviceName: string;
+    serviceVersion?: string;
+}
+declare function initInstrumentation(config: InstrumentationConfig): void;
+declare function shutdownInstrumentation(): Promise<void>;
+/**
+ * Trace a function execution with automatic error recording and timing.
+ * Use for key operations like cold starts, builds, tool calls, etc.
+ */
+declare function traceOperation<T>(tracerName: string, spanName: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T>): Promise<T>;
+
+export { type InstrumentationConfig, initInstrumentation, shutdownInstrumentation, traceOperation };

package/dist/instrumentation.d.ts

@@ -0,0 +1,43 @@
+import { Span } from '@opentelemetry/api';
+
+/**
+ * OpenTelemetry tracing setup for Shogo runtime services.
+ *
+ * Wires a `NodeSDK` with an OTLP HTTP trace exporter pointed at
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`, optionally authenticated via
+ * `SIGNOZ_INGESTION_KEY`. In production / staging, spans are batched
+ * before flush; in development a `SimpleSpanProcessor` flushes
+ * eagerly so traces are visible immediately.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT.
+ * The OpenTelemetry packages are optional `peerDependencies` of the SDK
+ * — only consumers that actually call `initInstrumentation` need them
+ * installed.
+ *
+ * @example
+ *   import { initInstrumentation, traceOperation, shutdownInstrumentation }
+ *     from '@shogo-ai/sdk/instrumentation'
+ *
+ *   initInstrumentation({ serviceName: 'my-api', serviceVersion: '1.0.0' })
+ *
+ *   await traceOperation('my-api', 'cold-start', { region: 'us-west' }, async (span) => {
+ *     // ... boot work ...
+ *     span.setAttribute('warm-pool-size', 4)
+ *   })
+ *
+ *   process.on('SIGTERM', () => shutdownInstrumentation())
+ */
+
+interface InstrumentationConfig {
+    serviceName: string;
+    serviceVersion?: string;
+}
+declare function initInstrumentation(config: InstrumentationConfig): void;
+declare function shutdownInstrumentation(): Promise<void>;
+/**
+ * Trace a function execution with automatic error recording and timing.
+ * Use for key operations like cold starts, builds, tool calls, etc.
+ */
+declare function traceOperation<T>(tracerName: string, spanName: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T>): Promise<T>;
+
+export { type InstrumentationConfig, initInstrumentation, shutdownInstrumentation, traceOperation };

package/dist/instrumentation.js

@@ -0,0 +1,11 @@
+import {
+  initInstrumentation,
+  shutdownInstrumentation,
+  traceOperation
+} from "./chunk-IDGVRGAL.js";
+export {
+  initInstrumentation,
+  shutdownInstrumentation,
+  traceOperation
+};
+//# sourceMappingURL=instrumentation.js.map

package/dist/logger.cjs

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/logger.ts
+var logger_exports = {};
+__export(logger_exports, {
+  createLogger: () => createLogger
+});
+module.exports = __toCommonJS(logger_exports);
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var isProduction = process.env.NODE_ENV === "production" || process.env.NODE_ENV === "staging";
+var minLevel = LOG_LEVELS[process.env.LOG_LEVEL || "info"] ?? 1;
+function shouldLog(level) {
+  return LOG_LEVELS[level] >= minLevel;
+}
+function formatEntry(entry) {
+  if (isProduction) {
+    return JSON.stringify(entry);
+  }
+  const { level: _level, msg, service, timestamp: _timestamp, ...extra } = entry;
+  const extraStr = Object.keys(extra).length > 0 ? " " + JSON.stringify(extra) : "";
+  return `[${service}] ${msg}${extraStr}`;
+}
+function createLogger(service, defaultExtra) {
+  function log(level, msg, extra) {
+    if (!shouldLog(level)) return;
+    const entry = {
+      level,
+      msg,
+      service,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...defaultExtra,
+      ...extra
+    };
+    const formatted = formatEntry(entry);
+    switch (level) {
+      case "error":
+        console.error(formatted);
+        break;
+      case "warn":
+        console.warn(formatted);
+        break;
+      default:
+        console.log(formatted);
+        break;
+    }
+  }
+  return {
+    debug: (msg, extra) => log("debug", msg, extra),
+    info: (msg, extra) => log("info", msg, extra),
+    warn: (msg, extra) => log("warn", msg, extra),
+    error: (msg, extra) => log("error", msg, extra),
+    child: (extra) => createLogger(service, { ...defaultExtra, ...extra })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createLogger
+});
+//# sourceMappingURL=logger.cjs.map

package/dist/logger.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Structured logger for Shogo runtime services.
+ *
+ * Outputs JSON lines in production / staging (suitable for SigNoz log
+ * collection or any structured log pipeline) and a human-readable
+ * `[service] msg {extra}` format in development.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT
+ * so userland agent/app code can import the same logger the runtime
+ * services use without dragging an AGPL workspace dependency.
+ *
+ * @example
+ *   import { createLogger } from '@shogo-ai/sdk/logger'
+ *
+ *   const log = createLogger('my-service')
+ *   log.info('boot complete', { port: 8002 })
+ *
+ *   const reqLog = log.child({ requestId: 'r-123' })
+ *   reqLog.warn('slow query', { ms: 4200 })
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface Logger {
+    debug(msg: string, extra?: Record<string, unknown>): void;
+    info(msg: string, extra?: Record<string, unknown>): void;
+    warn(msg: string, extra?: Record<string, unknown>): void;
+    error(msg: string, extra?: Record<string, unknown>): void;
+    /** Returns a new logger that merges `extra` into every log entry. */
+    child(extra: Record<string, unknown>): Logger;
+}
+declare function createLogger(service: string, defaultExtra?: Record<string, unknown>): Logger;
+
+export { type LogLevel, type Logger, createLogger };

package/dist/logger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Structured logger for Shogo runtime services.
+ *
+ * Outputs JSON lines in production / staging (suitable for SigNoz log
+ * collection or any structured log pipeline) and a human-readable
+ * `[service] msg {extra}` format in development.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT
+ * so userland agent/app code can import the same logger the runtime
+ * services use without dragging an AGPL workspace dependency.
+ *
+ * @example
+ *   import { createLogger } from '@shogo-ai/sdk/logger'
+ *
+ *   const log = createLogger('my-service')
+ *   log.info('boot complete', { port: 8002 })
+ *
+ *   const reqLog = log.child({ requestId: 'r-123' })
+ *   reqLog.warn('slow query', { ms: 4200 })
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface Logger {
+    debug(msg: string, extra?: Record<string, unknown>): void;
+    info(msg: string, extra?: Record<string, unknown>): void;
+    warn(msg: string, extra?: Record<string, unknown>): void;
+    error(msg: string, extra?: Record<string, unknown>): void;
+    /** Returns a new logger that merges `extra` into every log entry. */
+    child(extra: Record<string, unknown>): Logger;
+}
+declare function createLogger(service: string, defaultExtra?: Record<string, unknown>): Logger;
+
+export { type LogLevel, type Logger, createLogger };

package/dist/logger.js

@@ -0,0 +1,7 @@
+import {
+  createLogger
+} from "./chunk-24AL3V6R.js";
+export {
+  createLogger
+};
+//# sourceMappingURL=logger.js.map

package/dist/macos-junk.cjs

@@ -0,0 +1,56 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/macos-junk.ts
+var macos_junk_exports = {};
+__export(macos_junk_exports, {
+  isMacOSJunkName: () => isMacOSJunkName,
+  isMacOSJunkPath: () => isMacOSJunkPath
+});
+module.exports = __toCommonJS(macos_junk_exports);
+var MACOS_JUNK_BASENAMES = /* @__PURE__ */ new Set([
+  ".DS_Store",
+  ".AppleDouble",
+  ".LSOverride",
+  ".Spotlight-V100",
+  ".Trashes",
+  ".fseventsd",
+  ".TemporaryItems",
+  ".VolumeIcon.icns",
+  ".com.apple.timemachine.donotpresent",
+  "__MACOSX"
+]);
+var ICON_CR = "Icon\r";
+function isMacOSJunkName(name) {
+  if (!name) return false;
+  if (name.startsWith("._")) return true;
+  if (MACOS_JUNK_BASENAMES.has(name)) return true;
+  if (name === ICON_CR) return true;
+  return false;
+}
+function isMacOSJunkPath(relPath) {
+  if (!relPath) return false;
+  return relPath.split("/").some(isMacOSJunkName);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isMacOSJunkName,
+  isMacOSJunkPath
+});
+//# sourceMappingURL=macos-junk.cjs.map

package/dist/macos-junk.d.cts

@@ -0,0 +1,20 @@
+/**
+ * Filter for macOS-specific filesystem detritus that must never round-trip
+ * through a project export. The motivating bug: AppleDouble sidecars
+ * (`._foo.ts`, `._\_layout.tsx`) are binary resource-fork blobs but share
+ * the source-file extension. When an imported workspace contains them,
+ * Metro's Babel parser tries to parse `._\_layout.tsx` as TypeScript and
+ * crashes the bundler.
+ *
+ * Used by every export path (S3 sync tar, /download tar, .shogo-project
+ * ZIP, agent-runtime workspace bundle) and by the post-extract scrubber so
+ * legacy archives already in S3 also get cleaned on import.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT.
+ * The original `@shogo/shared-runtime/macos-junk` re-exports this module
+ * unchanged for backwards compatibility.
+ */
+declare function isMacOSJunkName(name: string): boolean;
+declare function isMacOSJunkPath(relPath: string): boolean;
+
+export { isMacOSJunkName, isMacOSJunkPath };

package/dist/macos-junk.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Filter for macOS-specific filesystem detritus that must never round-trip
+ * through a project export. The motivating bug: AppleDouble sidecars
+ * (`._foo.ts`, `._\_layout.tsx`) are binary resource-fork blobs but share
+ * the source-file extension. When an imported workspace contains them,
+ * Metro's Babel parser tries to parse `._\_layout.tsx` as TypeScript and
+ * crashes the bundler.
+ *
+ * Used by every export path (S3 sync tar, /download tar, .shogo-project
+ * ZIP, agent-runtime workspace bundle) and by the post-extract scrubber so
+ * legacy archives already in S3 also get cleaned on import.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT.
+ * The original `@shogo/shared-runtime/macos-junk` re-exports this module
+ * unchanged for backwards compatibility.
+ */
+declare function isMacOSJunkName(name: string): boolean;
+declare function isMacOSJunkPath(relPath: string): boolean;
+
+export { isMacOSJunkName, isMacOSJunkPath };

package/dist/macos-junk.js

@@ -0,0 +1,9 @@
+import {
+  isMacOSJunkName,
+  isMacOSJunkPath
+} from "./chunk-VTD7O7YC.js";
+export {
+  isMacOSJunkName,
+  isMacOSJunkPath
+};
+//# sourceMappingURL=macos-junk.js.map

package/dist/stream-buffer.cjs

@@ -0,0 +1,261 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/stream-buffer.ts
+var stream_buffer_exports = {};
+__export(stream_buffer_exports, {
+  StreamBufferStore: () => StreamBufferStore,
+  createBufferingTransform: () => createBufferingTransform
+});
+module.exports = __toCommonJS(stream_buffer_exports);
+var CLEANUP_INTERVAL_MS = 6e4;
+var MAX_BUFFER_AGE_MS = 30 * 6e4;
+var COMPLETED_GRACE_MS = 3e4;
+var StreamBufferStore = class {
+  constructor() {
+    this.buffers = /* @__PURE__ */ new Map();
+    this.cleanupTimer = null;
+    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
+    const handle = this.cleanupTimer;
+    if (handle && typeof handle.unref === "function") {
+      handle.unref();
+    }
+  }
+  /**
+   * Create (or replace) a buffer for the given key. Any existing active
+   * buffer is completed and discarded. Returns a writer bound to this
+   * specific buffer instance, including the new `turnId`.
+   */
+  create(key, opts) {
+    const existing = this.buffers.get(key);
+    if (existing && existing.status === "active") {
+      this.completeBuffer(existing, "replaced");
+    }
+    const now = Date.now();
+    const turnId = opts?.turnId || generateTurnId();
+    const buf = {
+      turnId,
+      frames: [],
+      subscribers: /* @__PURE__ */ new Set(),
+      status: "active",
+      terminal: null,
+      createdAt: now,
+      completedAt: null,
+      lastEventAt: now,
+      nextSeq: 1
+    };
+    this.buffers.set(key, buf);
+    return {
+      get turnId() {
+        return buf.turnId;
+      },
+      get lastSeq() {
+        return buf.nextSeq - 1;
+      },
+      append: (chunk) => {
+        if (buf.status !== "active") return -1;
+        const seq = buf.nextSeq++;
+        buf.frames.push({ seq, chunk });
+        buf.lastEventAt = Date.now();
+        for (const ctrl of buf.subscribers) {
+          try {
+            ctrl.enqueue(chunk);
+          } catch {
+            buf.subscribers.delete(ctrl);
+          }
+        }
+        return seq;
+      },
+      complete: (reason) => {
+        this.completeBuffer(buf, reason);
+      },
+      fail: (error) => {
+        this.failBuffer(buf, error);
+      }
+    };
+  }
+  /**
+   * Append a chunk by key (loose, untyped writer). Returns the seq assigned,
+   * or -1 if the buffer is unknown/inactive.
+   */
+  append(key, chunk) {
+    const buf = this.buffers.get(key);
+    if (!buf || buf.status !== "active") return -1;
+    const seq = buf.nextSeq++;
+    buf.frames.push({ seq, chunk });
+    buf.lastEventAt = Date.now();
+    for (const ctrl of buf.subscribers) {
+      try {
+        ctrl.enqueue(chunk);
+      } catch {
+        buf.subscribers.delete(ctrl);
+      }
+    }
+    return seq;
+  }
+  /** Mark a buffer as completed by key. Optional terminal reason. */
+  complete(key, reason) {
+    const buf = this.buffers.get(key);
+    if (!buf) return;
+    this.completeBuffer(buf, reason);
+  }
+  /**
+   * Abort a stream: complete subscribers and remove the buffer entirely.
+   * Future resume/replay requests for this key will return null (→ 204).
+   */
+  abort(key) {
+    const buf = this.buffers.get(key);
+    if (!buf) return;
+    this.completeBuffer(buf, "aborted");
+    buf.status = "aborted";
+    this.buffers.delete(key);
+  }
+  has(key) {
+    return this.buffers.has(key);
+  }
+  /** Read-only metadata about a buffered turn. Useful for resume responses. */
+  snapshot(key) {
+    const buf = this.buffers.get(key);
+    if (!buf) return null;
+    return {
+      turnId: buf.turnId,
+      status: buf.status,
+      lastSeq: buf.nextSeq - 1,
+      terminal: buf.terminal,
+      createdAt: buf.createdAt,
+      completedAt: buf.completedAt,
+      lastEventAt: buf.lastEventAt
+    };
+  }
+  /**
+   * Create a ReadableStream that first replays all buffered chunks past
+   * `opts.fromSeq` (default: 0 → replay everything), then subscribes for
+   * any further live chunks until the stream completes.
+   *
+   * Returns null if no buffer exists for the key.
+   */
+  createReplayStream(key, opts = {}) {
+    const buf = this.buffers.get(key);
+    if (!buf) return null;
+    const fromSeq = Math.max(0, opts.fromSeq ?? 0);
+    let subscribedController = null;
+    return new ReadableStream({
+      start(controller) {
+        for (const frame of buf.frames) {
+          if (frame.seq <= fromSeq) continue;
+          try {
+            controller.enqueue(frame.chunk);
+          } catch {
+            return;
+          }
+        }
+        if (buf.status !== "active") {
+          try {
+            controller.close();
+          } catch {
+          }
+          return;
+        }
+        subscribedController = controller;
+        buf.subscribers.add(controller);
+      },
+      cancel() {
+        if (subscribedController) {
+          buf.subscribers.delete(subscribedController);
+          subscribedController = null;
+        }
+      }
+    });
+  }
+  cleanup() {
+    const now = Date.now();
+    for (const [key, buf] of this.buffers) {
+      if (buf.status !== "active" && buf.completedAt && now - buf.completedAt > COMPLETED_GRACE_MS) {
+        this.buffers.delete(key);
+      } else if (now - buf.createdAt > MAX_BUFFER_AGE_MS && buf.subscribers.size === 0) {
+        this.completeBuffer(buf, "expired");
+        this.buffers.delete(key);
+      }
+    }
+  }
+  dispose() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    for (const buf of this.buffers.values()) {
+      this.completeBuffer(buf, "disposed");
+    }
+    this.buffers.clear();
+  }
+  completeBuffer(buf, reason) {
+    if (buf.status !== "active") return;
+    buf.status = "completed";
+    buf.terminal = { reason };
+    buf.completedAt = Date.now();
+    buf.lastEventAt = buf.completedAt;
+    for (const ctrl of buf.subscribers) {
+      try {
+        ctrl.close();
+      } catch {
+      }
+    }
+    buf.subscribers.clear();
+  }
+  failBuffer(buf, error) {
+    if (buf.status !== "active") return;
+    buf.status = "failed";
+    buf.terminal = { error };
+    buf.completedAt = Date.now();
+    buf.lastEventAt = buf.completedAt;
+    for (const ctrl of buf.subscribers) {
+      try {
+        ctrl.close();
+      } catch {
+      }
+    }
+    buf.subscribers.clear();
+  }
+};
+function generateTurnId() {
+  try {
+    if (typeof globalThis.crypto?.randomUUID === "function") {
+      return globalThis.crypto.randomUUID();
+    }
+  } catch {
+  }
+  return `turn_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function createBufferingTransform(store, key) {
+  return new TransformStream({
+    transform(chunk, controller) {
+      store.append(key, chunk);
+      controller.enqueue(chunk);
+    },
+    flush() {
+      store.complete(key);
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StreamBufferStore,
+  createBufferingTransform
+});
+//# sourceMappingURL=stream-buffer.cjs.map