@shogo-ai/core 1.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shogo Technologies, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (C) 2026 Shogo Technologies, Inc. -->
+
+# @shogo-ai/core
+
+Shogo Core — generic, dependency-light utilities used across the Shogo
+SDK family. Zero required peer dependencies; OpenTelemetry is opt-in.
+
+## Subpath exports
+
+| Subpath | What |
+| --- | --- |
+| `@shogo-ai/core/logger` | Structured leveled logger with pluggable sinks. |
+| `@shogo-ai/core/instrumentation` | Thin OpenTelemetry tracing wrapper that no-ops if `@opentelemetry/api` isn't installed. |
+| `@shogo-ai/core/stream-buffer` | In-memory ring-buffered text stream. |
+| `@shogo-ai/core/chat-message` | Minimal chat-message types shared by `@shogo-ai/agent` and downstream consumers. |
+
+## Optional peers
+
+Install OpenTelemetry packages only if you import
+`@shogo-ai/core/instrumentation` and want real spans (otherwise the
+wrapper no-ops):
+
+```bash
+bun add -d @opentelemetry/api @opentelemetry/sdk-node \
+  @opentelemetry/exporter-trace-otlp-http \
+  @opentelemetry/sdk-trace-base \
+  @opentelemetry/resources \
+  @opentelemetry/semantic-conventions
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chat-message.cjs

@@ -0,0 +1,44 @@
+"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/chat-message.ts
+var chat_message_exports = {};
+__export(chat_message_exports, {
+  extractUserText: () => extractUserText,
+  findLastUserMessage: () => findLastUserMessage
+});
+module.exports = __toCommonJS(chat_message_exports);
+function findLastUserMessage(messages) {
+  return [...messages].reverse().find((m) => m.role === "user") ?? null;
+}
+function extractUserText(message) {
+  if (typeof message.content === "string") {
+    return message.content;
+  }
+  if (Array.isArray(message.parts)) {
+    return message.parts.filter((p) => p.type === "text").map((p) => p.text).join("\n");
+  }
+  return String(message.content ?? "");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  extractUserText,
+  findLastUserMessage
+});
+//# sourceMappingURL=chat-message.cjs.map

package/dist/chat-message.d.cts

@@ -0,0 +1,20 @@
+/**
+ * User message extraction for AI SDK v3 (`parts`) and legacy (`content`)
+ * message shapes. Useful when you need plain text from a chat history —
+ * e.g. for fingerprinting, logging, or short-circuit routing decisions
+ * before the message hits an LLM.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT.
+ * The original `@shogo/shared-runtime/chat-message` re-exports this
+ * module unchanged for backwards compatibility.
+ */
+/** Find the last user message in a messages array. */
+declare function findLastUserMessage(messages: any[]): any | null;
+/**
+ * Extract plain text from a user message object.
+ * Handles AI SDK v3 `parts` format, legacy `content` string,
+ * and legacy `content` array format.
+ */
+declare function extractUserText(message: any): string;
+
+export { extractUserText, findLastUserMessage };

package/dist/chat-message.d.ts

@@ -0,0 +1,20 @@
+/**
+ * User message extraction for AI SDK v3 (`parts`) and legacy (`content`)
+ * message shapes. Useful when you need plain text from a chat history —
+ * e.g. for fingerprinting, logging, or short-circuit routing decisions
+ * before the message hits an LLM.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT.
+ * The original `@shogo/shared-runtime/chat-message` re-exports this
+ * module unchanged for backwards compatibility.
+ */
+/** Find the last user message in a messages array. */
+declare function findLastUserMessage(messages: any[]): any | null;
+/**
+ * Extract plain text from a user message object.
+ * Handles AI SDK v3 `parts` format, legacy `content` string,
+ * and legacy `content` array format.
+ */
+declare function extractUserText(message: any): string;
+
+export { extractUserText, findLastUserMessage };

package/dist/chat-message.js

@@ -0,0 +1,9 @@
+import {
+  extractUserText,
+  findLastUserMessage
+} from "./chunk-4J7NH2WJ.js";
+export {
+  extractUserText,
+  findLastUserMessage
+};
+//# sourceMappingURL=chat-message.js.map

package/dist/chunk-24AL3V6R.js

@@ -0,0 +1,57 @@
+// src/logger.ts
+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 })
+  };
+}
+
+export {
+  createLogger
+};
+//# sourceMappingURL=chunk-24AL3V6R.js.map

package/dist/chunk-4J7NH2WJ.js

@@ -0,0 +1,19 @@
+// src/chat-message.ts
+function findLastUserMessage(messages) {
+  return [...messages].reverse().find((m) => m.role === "user") ?? null;
+}
+function extractUserText(message) {
+  if (typeof message.content === "string") {
+    return message.content;
+  }
+  if (Array.isArray(message.parts)) {
+    return message.parts.filter((p) => p.type === "text").map((p) => p.text).join("\n");
+  }
+  return String(message.content ?? "");
+}
+
+export {
+  findLastUserMessage,
+  extractUserText
+};
+//# sourceMappingURL=chunk-4J7NH2WJ.js.map

package/dist/chunk-ELMG6OXT.js

@@ -0,0 +1,236 @@
+// src/stream-buffer.ts
+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);
+    }
+  });
+}
+
+export {
+  StreamBufferStore,
+  createBufferingTransform
+};
+//# sourceMappingURL=chunk-ELMG6OXT.js.map

package/dist/chunk-IDGVRGAL.js

@@ -0,0 +1,103 @@
+// src/instrumentation.ts
+import { diag, DiagConsoleLogger, DiagLogLevel, trace, SpanStatusCode } from "@opentelemetry/api";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchSpanProcessor, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+var sdk = null;
+function initInstrumentation(config) {
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (!endpoint) {
+    console.log(`[OTEL] Tracing disabled for ${config.serviceName} (OTEL_EXPORTER_OTLP_ENDPOINT not set)`);
+    return;
+  }
+  const diagLevel = process.env.OTEL_LOG_LEVEL === "debug" ? DiagLogLevel.DEBUG : process.env.OTEL_LOG_LEVEL === "info" ? DiagLogLevel.INFO : DiagLogLevel.WARN;
+  diag.setLogger(new DiagConsoleLogger(), diagLevel);
+  const headers = {};
+  if (process.env.SIGNOZ_INGESTION_KEY) {
+    headers["signoz-ingestion-key"] = process.env.SIGNOZ_INGESTION_KEY;
+  }
+  const serviceName = process.env.OTEL_SERVICE_NAME || config.serviceName;
+  console.log(`[OTEL] Configuring ${serviceName} \u2192 ${endpoint}/v1/traces`);
+  let traceExporter;
+  try {
+    traceExporter = new OTLPTraceExporter({
+      url: `${endpoint}/v1/traces`,
+      headers
+    });
+  } catch (err) {
+    console.error(`[OTEL] Failed to create exporter: ${err.message}`);
+    return;
+  }
+  const isProduction = process.env.NODE_ENV === "production" || process.env.NODE_ENV === "staging";
+  const spanProcessor = isProduction ? new BatchSpanProcessor(traceExporter) : new SimpleSpanProcessor(traceExporter);
+  sdk = new NodeSDK({
+    resource: resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: serviceName,
+      [ATTR_SERVICE_VERSION]: config.serviceVersion || "0.1.0",
+      "deployment.environment.name": process.env.NODE_ENV || "development"
+    }),
+    spanProcessors: [spanProcessor],
+    instrumentations: []
+  });
+  try {
+    sdk.start();
+    console.log(`[OTEL] Tracing enabled for ${serviceName}`);
+  } catch (err) {
+    console.error(`[OTEL] SDK failed to start: ${err.message}`);
+    sdk = null;
+    return;
+  }
+  try {
+    const tracer = trace.getTracer(serviceName);
+    const testSpan = tracer.startSpan("otel.startup-test", {
+      attributes: {
+        "test.type": "startup-verification",
+        "service.name": serviceName,
+        // `process.versions.bun` is present under Bun (always undefined
+        // under plain Node) — avoids referencing the `Bun` global so
+        // this file typechecks without `@types/bun` in tsconfig.
+        "runtime": process.versions.bun ? "bun" : "node"
+      }
+    });
+    testSpan.setStatus({ code: SpanStatusCode.OK });
+    testSpan.end();
+    console.log(`[OTEL] Startup test span emitted for ${serviceName}`);
+  } catch (err) {
+    console.error(`[OTEL] Failed to emit test span: ${err.message}`);
+  }
+}
+async function shutdownInstrumentation() {
+  if (sdk) {
+    try {
+      await sdk.shutdown();
+      console.log("[OTEL] Tracing shut down");
+    } catch (err) {
+      console.error("[OTEL] Error shutting down:", err.message);
+    }
+  }
+}
+function traceOperation(tracerName, spanName, attributes, fn) {
+  const tracer = trace.getTracer(tracerName);
+  return tracer.startActiveSpan(spanName, { attributes }, async (span) => {
+    try {
+      const result = await fn(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (err) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+      span.recordException(err);
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+export {
+  initInstrumentation,
+  shutdownInstrumentation,
+  traceOperation
+};
+//# sourceMappingURL=chunk-IDGVRGAL.js.map

package/dist/chunk-KTDDFWXM.js

@@ -0,0 +1,39 @@
+// src/tech-stack-registry.ts
+var TECH_STACK_REGISTRY = {
+  // Web (Vite-based) — share a bundled Vite template, so apps/api seeds them.
+  "react-app": { id: "react-app", target: "web" },
+  "threejs-game": { id: "threejs-game", target: "web" },
+  "phaser-game": { id: "phaser-game", target: "web" },
+  // Mobile (Metro/Expo) — agent-runtime owns the seed.
+  "expo-app": { id: "expo-app", target: "mobile", metro: true, seedsOwnTemplate: true },
+  "expo-three": { id: "expo-three", target: "mobile", metro: true, seedsOwnTemplate: true },
+  "react-native": { id: "react-native", target: "mobile", metro: true, seedsOwnTemplate: true },
+  // Data / scripting
+  "python-data": { id: "python-data", target: "data", seedsOwnTemplate: true },
+  // Native (full game engines)
+  "unity-game": { id: "unity-game", target: "native", seedsOwnTemplate: true },
+  // Bare / no-stack
+  none: { id: "none", target: "none", seedsOwnTemplate: true }
+};
+function getStackEntry(techStackId) {
+  if (!techStackId) return null;
+  return TECH_STACK_REGISTRY[techStackId] ?? null;
+}
+function isMobileTechStack(techStackId) {
+  return getStackEntry(techStackId)?.target === "mobile";
+}
+function usesMetroBundler(techStackId) {
+  return getStackEntry(techStackId)?.metro === true;
+}
+function stackSeedsItself(techStackId) {
+  return getStackEntry(techStackId)?.seedsOwnTemplate === true;
+}
+
+export {
+  TECH_STACK_REGISTRY,
+  getStackEntry,
+  isMobileTechStack,
+  usesMetroBundler,
+  stackSeedsItself
+};
+//# sourceMappingURL=chunk-KTDDFWXM.js.map

package/dist/chunk-VTD7O7YC.js

@@ -0,0 +1,31 @@
+// src/macos-junk.ts
+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);
+}
+
+export {
+  isMacOSJunkName,
+  isMacOSJunkPath
+};
+//# sourceMappingURL=chunk-VTD7O7YC.js.map