@prismshadow/penguin-core 0.0.1

package/dist/types-D6FERSdT.d.ts

@@ -0,0 +1,293 @@
+/**
+ * OmniMessage — PenguinHarness's primary message protocol.
+ *
+ * All messages share one envelope: `timestamp` (ISO 8601 UTC), `type`, and `payload`.
+ * The outer `type` falls into three categories:
+ *   - `session_meta`: Session metadata;
+ *   - `model_msg`: model input/output messages (both complete messages and streaming
+ *     `partial_*` messages);
+ *   - `event_msg`: control/statistics events during execution.
+ *
+ * Trace records only: `session_meta`, complete `model_msg`, and all `event_msg`;
+ * the Human interface communicates using: complete `model_msg`, streaming `partial_*`, and all
+ * `event_msg`.
+ *
+ * Docs: packages/docs/content/omni-message.{zh,en}.md (site path /docs/omni-message) documents
+ * this protocol payload-for-payload — keep the page in sync when changing types here.
+ */
+/** The outer message category. */
+type OmniMessageType = "session_meta" | "model_msg" | "event_msg";
+/** The message's originating role. */
+type Role = "user" | "assistant";
+/**
+ * The reason a model response or message generation ended. Only five protocol values are
+ * allowed:
+ *   - `completed`: finished normally, including completed text, thinking, tool requests, or
+ *     tool output;
+ *   - `failed`: a non-retryable error or tool execution failure;
+ *   - `aborted`: user-initiated interruption or cancellation;
+ *   - `timeout`: LLM request timed out;
+ *   - `malformed`: the LLM response was malformed (e.g. AgentHub JSON parsing exception).
+ *     Only LLM timeout / malformed trigger a context_engine reconnect.
+ * Docs: /docs/omni-message § "stop_reason".
+ */
+type StopReason = "completed" | "failed" | "aborted" | "timeout" | "malformed";
+/** The event phase of a streaming fragment. `stop` marks the end of a fragment and usually carries no incremental content. */
+type StreamEventType = "start" | "delta" | "stop";
+/**
+ * Nested-origin marker: a child Session id. The message envelope's `origin` is a chain of child
+ * Session ids ordered **outer-to-inner**, identifying that the message comes from a nested child
+ * session (e.g. a child Session derived by `run_subagent`); each layer of host-tool forwarding
+ * prepends one more hop at the front. **An absent `origin` (the message carries no `origin`)
+ * means the message comes from the main Session itself** (an empty array is never produced
+ * either). Only session_id is recorded: the corresponding tool_call / agent info can be obtained
+ * from the `run_subagent` tool_call in the parent session's stream and the child Session's own
+ * Trace (session_meta).
+ * Docs: /docs/omni-message § "origin: the Subagent chain".
+ */
+type MessageOrigin = string;
+/** The approval decision for a tool call. */
+type ApprovalDecision = "allow" | "deny";
+/** Token counts (input/output/cache/total). */
+interface TokenCounts {
+    cache_read: number;
+    cache_write: number;
+    output: number;
+    total: number;
+}
+/** Tool definition passed to the LLM (OpenAI/JSON Schema style). */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+}
+interface SessionMetaPayload {
+    session_id: string;
+    /** The session model's provider group (paired with `model_id` to form a model reference). */
+    provider: string;
+    /** The session model's upstream model_id (the request id sent to AgentHub; paired with `provider`). */
+    model_id: string;
+    model_context_window: number | string;
+    /** The system prompt actually used by this Session (the assembled result with environment placeholders already substituted). */
+    system_prompt: string;
+    /** The list of tool definitions this Session exposes to the model (full schema, matching what's sent to the LLM). */
+    tools: ToolDefinition[];
+    /** The model's thinking level (from system_config.model.thinking_level; "default" when unconfigured). */
+    thinking_level: string;
+    /** Absolute path to the Agent State. */
+    agent_state: string;
+    /** Absolute path to the Workspace. */
+    workspace: string;
+}
+interface TextPayload {
+    type: "text";
+    role: Role;
+    text: string;
+    stop_reason?: StopReason;
+    /** Provider fidelity field: text phase marker (e.g. GPT-5 segments by phase), kept as-is and restored verbatim. */
+    phase?: string | null;
+    /** Provider fidelity field: signature, kept as-is and restored verbatim. */
+    signature?: string;
+}
+interface ImageUrlPayload {
+    type: "image_url";
+    role: "user";
+    /** A web URL or a base64 data URL. */
+    image_url: string;
+    stop_reason?: StopReason;
+}
+interface InlineDataPayload {
+    type: "inline_data";
+    role: Role;
+    /** Base64-encoded bytes. */
+    data: string;
+    mime_type: string;
+    stop_reason?: StopReason;
+    /** Provider fidelity field: signature, kept as-is and restored verbatim. */
+    signature?: string;
+}
+interface ThinkingPayload {
+    type: "thinking";
+    role: "assistant";
+    thinking: string;
+    stop_reason?: StopReason;
+    /**
+     * Provider fidelity field: thinking-block signature (Claude thinking blocks / redacted
+     * thinking, GPT-5 encrypted reasoning, etc. — **required** when some models replay history),
+     * kept as-is and restored verbatim — losing it breaks Session resumption.
+     */
+    signature?: string;
+}
+interface InlineThinkingPayload {
+    type: "inline_thinking";
+    role: "assistant";
+    /** Base64-encoded bytes. */
+    data: string;
+    mime_type: string;
+    stop_reason?: StopReason;
+    /** Provider fidelity field: signature, kept as-is and restored verbatim. */
+    signature?: string;
+}
+interface ToolCallPayload {
+    type: "tool_call";
+    role: "assistant";
+    name: string;
+    /** Tool arguments as a JSON string. */
+    arguments: string;
+    tool_call_id: string;
+    stop_reason?: StopReason;
+    /** Provider fidelity field: signature, kept as-is and restored verbatim. */
+    signature?: string;
+}
+interface ToolCallOutputPayload {
+    type: "tool_call_output";
+    role: "user";
+    output: string;
+    /**
+     * Images carried by the tool output (optional): each is a `data:<mime>;base64,...` data URL,
+     * fed back to the model alongside the text (e.g. images read by read_image). Images aren't
+     * incremental: the streaming path carries the whole set once via a single delta (see
+     * `PartialToolCallOutputPayload.images`), and the complete message carries them again — the
+     * streamed-and-joined result equals the complete message.
+     */
+    images?: string[];
+    tool_call_id: string;
+    stop_reason?: StopReason;
+}
+interface PartialTextPayload {
+    type: "partial_text";
+    role: "assistant";
+    event_type: StreamEventType;
+    text: string;
+    stop_reason?: StopReason;
+}
+interface PartialThinkingPayload {
+    type: "partial_thinking";
+    role: "assistant";
+    event_type: StreamEventType;
+    thinking: string;
+    stop_reason?: StopReason;
+}
+interface PartialToolCallPayload {
+    type: "partial_tool_call";
+    role: "assistant";
+    event_type: StreamEventType;
+    name: string;
+    /** Incremental fragment of the arguments JSON. */
+    arguments: string;
+    tool_call_id: string;
+    stop_reason?: StopReason;
+}
+interface PartialToolCallOutputPayload {
+    type: "partial_tool_call_output";
+    role: "user";
+    event_type: StreamEventType;
+    output: string;
+    /** Images carried by the tool output (optional): images aren't incremental, carried as a whole by a single delta (consistent with the complete message). */
+    images?: string[];
+    tool_call_id: string;
+    stop_reason?: StopReason;
+}
+interface ApprovalDecisionPayload {
+    type: "approval_decision";
+    decision: ApprovalDecision;
+    tool_call_id: string;
+}
+interface AbortPayload {
+    type: "abort";
+    reason?: string | null;
+}
+interface TokenUsagePayload {
+    type: "token_usage";
+    /** Current Session cumulative token usage. */
+    session: TokenCounts;
+    /** Token usage for the most recent Request. */
+    request: TokenCounts;
+}
+/**
+ * Request boundary event: the boundary of one LLM Request, produced **in pairs** by
+ * `context_engine` and written to Trace. `request_end`
+ * with `status` of `completed` means the turn has been committed by AgentHub — this is the
+ * mechanical criterion Trace replay (Session resumption) uses to determine whether a turn was
+ * committed, and it also gives performance analysis a basis for Request latency and turn counts.
+ * A compaction request produces this same event pair too (written to Trace only, not streamed).
+ */
+interface RequestBeginPayload {
+    type: "request_begin";
+}
+interface RequestEndPayload {
+    type: "request_end";
+    /** Terminal state of this Request (reuses the five StopReason values, sharing its source with this turn's complete message's stop_reason / LLMOutcome). */
+    status: StopReason;
+}
+/** Compaction trigger reason: context threshold / turn-count threshold / user-initiated request. */
+type CompactionReason = "context" | "turns" | "manual";
+/** Context compaction mode: summary relay / direct discard. */
+type CompactionMode = "summarize" | "discard";
+/**
+ * Compaction boundary event: the compaction process exposes
+ * only this event pair to Human, produced **in pairs** by `context_engine`. Both `reason` and
+ * `mode` are carried on both events, for stateless frontend rendering; `status` reuses the
+ * five-value `StopReason` protocol (compaction converges to a terminal state, taking
+ * `completed` / `failed` / `aborted` in practice — `timeout` / `malformed` are handled internally
+ * by the compaction request's existing retry mechanism, collapsing to `failed` once retries are
+ * exhausted).
+ */
+interface CompactionBeginPayload {
+    type: "compaction_begin";
+    reason: CompactionReason;
+    mode: CompactionMode;
+    /** Current context token usage (the most recent token_usage's request.total). */
+    context: number;
+    /** Session cumulative turn count. */
+    turns: number;
+}
+interface CompactionEndPayload {
+    type: "compaction_end";
+    reason: CompactionReason;
+    mode: CompactionMode;
+    /** Compaction result; non-`completed` means compaction was abandoned and the original context was kept. */
+    status: StopReason;
+}
+/**
+ * Subagent pointer event: when the parent Session spawns a
+ * **direct** child session, `context_engine` writes this to the parent Trace (not streamed),
+ * recording only the child session's Session id — the child session's other details live in its
+ * own Trace's `session_meta`. When the session is reopened, the server uses this to recursively
+ * expand the child Trace and reconstruct the `origin` chain; a grandchild session's pointer is
+ * recorded by the child Trace itself.
+ */
+interface SubagentPayload {
+    type: "subagent";
+    /** The direct child session's Session id. */
+    session_id: string;
+}
+/** Complete model_msg payload (written to Trace and exposed externally). */
+type CompleteModelPayload = TextPayload | ImageUrlPayload | InlineDataPayload | ThinkingPayload | InlineThinkingPayload | ToolCallPayload | ToolCallOutputPayload;
+/** Streaming model_msg payload. */
+type PartialModelPayload = PartialTextPayload | PartialThinkingPayload | PartialToolCallPayload | PartialToolCallOutputPayload;
+type ModelPayload = CompleteModelPayload | PartialModelPayload;
+type EventPayload = ApprovalDecisionPayload | AbortPayload | RequestBeginPayload | RequestEndPayload | TokenUsagePayload | CompactionBeginPayload | CompactionEndPayload | SubagentPayload;
+type OmniPayload = SessionMetaPayload | ModelPayload | EventPayload;
+/** The unified message envelope. */
+interface OmniMessage<P extends OmniPayload = OmniPayload> {
+    /** ISO 8601 UTC timestamp. */
+    timestamp: string;
+    type: OmniMessageType;
+    payload: P;
+    /** Nested-origin marker: the chain of child Session ids ordered outer-to-inner; absent = from the main Session (see MessageOrigin). */
+    origin?: MessageOrigin[];
+}
+type SessionMetaMessage = OmniMessage<SessionMetaPayload>;
+type ModelMessage = OmniMessage<ModelPayload>;
+type EventMessage = OmniMessage<EventPayload>;
+type CompleteModelMessage = OmniMessage<CompleteModelPayload>;
+type PartialModelMessage = OmniMessage<PartialModelPayload>;
+declare function isPartialPayload(p: OmniPayload): p is PartialModelPayload;
+declare function isModelMessage(msg: OmniMessage): msg is ModelMessage;
+declare function isEventMessage(msg: OmniMessage): msg is EventMessage;
+declare function isSessionMeta(msg: OmniMessage): msg is SessionMetaMessage;
+/** A complete model_msg (not partial_*), i.e. a message that can be written to Trace. */
+declare function isCompleteModelMessage(msg: OmniMessage): msg is CompleteModelMessage;
+
+export { type ApprovalDecision as A, type SubagentPayload as B, type CompactionMode as C, type TextPayload as D, type EventMessage as E, type ThinkingPayload as F, type TokenUsagePayload as G, type ToolCallOutputPayload as H, type ImageUrlPayload as I, isCompleteModelMessage as J, isEventMessage as K, isModelMessage as L, type MessageOrigin as M, isPartialPayload as N, type OmniMessage as O, type PartialModelMessage as P, isSessionMeta as Q, type RequestBeginPayload as R, type StopReason as S, type ToolDefinition as T, type ToolCallPayload as a, type TokenCounts as b, type CompleteModelMessage as c, type SessionMetaMessage as d, type SessionMetaPayload as e, type AbortPayload as f, type ApprovalDecisionPayload as g, type CompactionBeginPayload as h, type CompactionEndPayload as i, type CompactionReason as j, type CompleteModelPayload as k, type EventPayload as l, type InlineDataPayload as m, type InlineThinkingPayload as n, type ModelMessage as o, type ModelPayload as p, type OmniMessageType as q, type OmniPayload as r, type PartialModelPayload as s, type PartialTextPayload as t, type PartialThinkingPayload as u, type PartialToolCallOutputPayload as v, type PartialToolCallPayload as w, type RequestEndPayload as x, type Role as y, type StreamEventType as z };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@prismshadow/penguin-core",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "PenguinHarness core SDK: context_engine, OmniMessage protocol, LLM/Environment interfaces.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prism-Shadow/penguin-harness.git",
+    "directory": "packages/core"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./omnimessage": {
+      "types": "./dist/omnimessage/index.d.ts",
+      "import": "./dist/omnimessage/index.js"
+    },
+    "./interfaces": {
+      "types": "./dist/interfaces.d.ts",
+      "import": "./dist/interfaces.js"
+    },
+    "./model-catalog": {
+      "types": "./dist/state/model-catalog.d.ts",
+      "import": "./dist/state/model-catalog.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@prismshadow/agenthub": "^0.3.3",
+    "smol-toml": "^1.3.0",
+    "yaml": "^2.5.0",
+    "@prismshadow/penguin-skills": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "dotenv": "^17.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "test:e2e": "PENGUIN_E2E=1 vitest run test/llm.e2e.test.ts",
+    "build": "tsup"
+  }
+}