akanjs 3.0.0-beta.0 → 3.0.0-beta.10

package/common/index.ts

@@ -111,6 +111,7 @@ export { sleep } from "./sleep";
 export { splitVersion } from "./splitVersion";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute";
 export { TrustedProxy } from "./TrustedProxy";
+export { toPathSegments } from "./toPathSegments";
 export type * from "./types";
 export {
   type WebsocketAuthAckData,

package/common/pathGet.ts

@@ -1,13 +1,23 @@
+import { toPathSegments } from "./toPathSegments";
+
 type Indexable = Record<string | number, unknown>;
+type PathSegment = string | number;
 
 const isIndexable = (value: unknown): value is Indexable => Object(value) === value;
 
+const readChild = (container: Indexable, key: PathSegment) =>
+  container instanceof Map ? (container as Map<PathSegment, unknown>).get(key) : container[key];
+
 export const pathGet = (
   path: string | (string | number)[],
   obj: unknown,
   separator = ".",
   fallback: unknown = null,
 ): unknown => {
-  const properties = Array.isArray(path) ? path : path.split(separator);
-  return properties.reduce((prev, curr) => (isIndexable(prev) ? (prev[curr] ?? fallback) : fallback), obj);
+
+  const properties = separator === "." ? toPathSegments(path) : Array.isArray(path) ? [...path] : path.split(separator);
+  return properties.reduce<unknown>(
+    (prev, curr) => (isIndexable(prev) ? (readChild(prev, curr) ?? fallback) : fallback),
+    obj,
+  );
 };

package/common/pathSet.ts

@@ -1,10 +1,9 @@
+import { toPathSegments } from "./toPathSegments";
+
 type MutableIndexable = Record<string | number, unknown>;
 type PathSegment = string | number;
 type Container = MutableIndexable | Map<PathSegment, unknown>;
 
-const toPathSegments = (path: string | readonly PathSegment[]) =>
-  Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];
-
 const readChild = (container: Container, key: PathSegment) =>
   container instanceof Map ? container.get(key) : container[key];
 

package/common/toPathSegments.ts

@@ -0,0 +1,10 @@
+type PathSegment = string | number;
+
+/**
+ * The one definition of what a dotted path's segments are, so a path that writes and a path that reads cannot
+ * disagree about it. `a.0.b` and `a[0].b` are the same three segments — the bracket form is what a form field
+ * hands `writeOn<Model>`, and a read of the same path has to accept the same spelling or the agent can write
+ * somewhere it cannot read back.
+ */
+export const toPathSegments = (path: string | readonly PathSegment[]) =>
+  Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];

package/common/types.ts

@@ -5,7 +5,11 @@ export interface FetchPolicy<Returns = unknown> {
   onError?: (error: string) => void;
   token?: string;
   partial?: string[];
-  timeout?: number;
+  /**
+   * Milliseconds before this call is abandoned, `false` to wait as long as the runtime will. Overrides the
+   * endpoint's declared `timeout`, which overrides the client's own default.
+   */
+  timeout?: number | false;
   /**
    * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
    *

package/dictionary/agent.dictionary.ts

@@ -28,4 +28,12 @@ export const agentDictionary = serviceDictionary(["en", "ko"])
       "DeepSeek refused this turn with status {status}. Reason: {reason}",
       "DeepSeek가 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
     ],
+    openaiRequestFailed: [
+      "OpenAI refused this turn with status {status}. Reason: {reason}",
+      "OpenAI가 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
+    ],
+    anthropicRequestFailed: [
+      "Anthropic refused this turn with status {status}. Reason: {reason}",
+      "Anthropic이 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
+    ],
   });

package/dictionary/agentTurn.dictionary.ts

@@ -19,11 +19,15 @@ export const agentTurnDictionary = scalarDictionary(["en", "ko"])
       "클라이언트가 실행할 툴 호출 목록 ({ id, name, args })",
     ]),
     stop: t(["Stop", "종료 사유"]).desc([
-      "Why the turn ended — end, or toolUse when tool results are awaited",
-      "턴이 끝난 이유 — end 또는 툴 결과를 기다리는 toolUse",
+      "Why the turn ended — end, toolUse when tool results are awaited, or length when the provider cut it off",
+      "턴이 끝난 이유 — end, 툴 결과를 기다리는 toolUse, 프로바이더가 잘라낸 length",
     ]),
   }))
   .enum<AgentStop>("agentStop", (t) => ({
     end: t(["End", "종료"]).desc(["The final answer", "최종 응답"]),
     toolUse: t(["Tool Use", "툴 사용"]).desc(["The model awaits tool results", "모델이 툴 결과를 기다린다"]),
+    length: t(["Length", "길이 초과"]).desc([
+      "The provider's answer ceiling cut the turn off, so it is incomplete",
+      "프로바이더의 응답 상한에 걸려 턴이 잘렸다. 미완성이다",
+    ]),
   }));

package/dictionary/base.dictionary.ts

@@ -80,6 +80,12 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     agentVoiceFailed: ["The microphone could not be used.", "마이크를 사용할 수 없습니다."],
     agentAttach: ["Attach a file", "파일 첨부"],
     agentAttachRemove: ["Remove attachment", "첨부 제거"],
+    agentAttachReading: ["Reading…", "읽는 중…"],
+    agentReferenceRemove: ["Remove reference", "참조 제거"],
+    agentReferenceFailed: [
+      "{label} could not be read, so the agent has only its name.",
+      "{label}을(를) 읽지 못해 이름만 전달됩니다.",
+    ],
     agentAttachTooLarge: ["{name} is too large to attach.", "{name}은(는) 용량이 너무 커서 첨부할 수 없습니다."],
     agentAttachUnsupported: ["{name} cannot be attached here.", "{name}은(는) 여기에 첨부할 수 없습니다."],
     agentAttachDuplicate: ["{name} is already attached.", "{name}은(는) 이미 첨부되어 있습니다."],

package/fetch/agentTurn.ts

@@ -1,7 +1,7 @@
 import { Any, enumOf } from "akanjs/base";
 import { ConstantRegistry, via } from "akanjs/constant";
 
-export class AgentStop extends enumOf("agentStop", ["end", "toolUse"] as const) {}
+export class AgentStop extends enumOf("agentStop", ["end", "toolUse", "length"] as const) {}
 
 export class AgentTurn extends via((field) => ({
   text: field(String, { default: "" }), // the assistant's words; empty when the turn is only tool calls

package/fetch/client/fetchClient.ts

@@ -173,6 +173,13 @@ export class FetchClient {
         }
       : signal;
   }
+  /**
+   * The budget for every call that neither names one nor is served by an endpoint declaring one. `false` waits
+   * as long as the runtime will, which is the browser's own limit — minutes.
+   */
+  setTimeout(timeout?: number | false) {
+    this.http.setTimeout(timeout);
+  }
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
     this.http.setErrorConstructor(ErrorCls);
@@ -316,8 +323,9 @@ export class FetchClient {
           const url = FetchClient.makeHttpUrl(key, endpoint, prefix, argMap);
           const headers = this.#makeAuthHeaders(option);
           const baseUrl = option?.origin;
+          const timeout = option?.timeout ?? endpoint.timeout;
 
-          const requestQuery = () => this.http.get(url, { headers, baseUrl });
+          const requestQuery = () => this.http.get(url, { headers, baseUrl, timeout });
 
           const claim = baseUrl
             ? { value: requestQuery(), owned: true }
@@ -339,6 +347,7 @@ export class FetchClient {
           const response = await this.http.send(endpoint.method ?? "POST", url, body, {
             headers: this.#makeAuthHeaders(option),
             baseUrl: option?.origin,
+            timeout: option?.timeout ?? endpoint.timeout,
           });
           const parsedReturn = parseReturn(response, { crystalize: option?.crystalize ?? true });
           return parsedReturn;
@@ -827,7 +836,15 @@ export class FetchClient {
       connect = false,
       base,
       Err,
-    }: { origin?: string; connect?: boolean; base?: FetchProxy; Err?: ErrorConstructor } = {},
+      timeout,
+    }: {
+      origin?: string;
+      connect?: boolean;
+      base?: FetchProxy;
+      Err?: ErrorConstructor;
+      /** This app's own default request budget, for calls no endpoint and no caller gave one. */
+      timeout?: number | false;
+    } = {},
   ): {
     sig: ClientSignalMap<SigType>;
     fetch: SigType["fetch"];
@@ -838,6 +855,7 @@ export class FetchClient {
     const proxy =
       shared ??
       FetchClient.#makeProxy<unknown, Record<string, SliceMeta>>(new FetchClient(origin, {}, serializedSignal, Err));
+    if (timeout !== undefined) proxy.instance.setTimeout(timeout);
     if (connect) proxy.instance.connect();
     const sig = {} as any;
     Object.entries(serializedSignal).forEach(([refName, serializedSignal]) => {

package/fetch/client/httpClient.ts

@@ -49,6 +49,10 @@ export class HttpClient {
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
   }
+  /** The budget every call that names none takes. `false` waits as long as the runtime will. */
+  setTimeout(timeout?: number | false) {
+    this.#timeout = timeout;
+  }
   #resolveBaseUrl(baseUrl?: string) {
     return (baseUrl ?? this.baseUrl).replace(/\/$/, "");
   }

package/fetch/client/wsClient.ts

@@ -171,13 +171,13 @@ export class WsClient {
             break;
         }
       } catch (error) {
-        this.logger.warn("WebSocket message process failed");
-        console.error(error);
+        const errMsg = error instanceof Error ? error.message : String(error);
+        this.logger.warn(`WebSocket message process failed ${errMsg}`);
       }
     };
     this.#ws.onerror = (e) => {
-      this.logger.debug(`WebSocket error`);
-      console.error(e);
+      const errMsg = e instanceof Error ? e.message : String(e);
+      this.logger.verbose(`WebSocket error ${errMsg}`);
     };
     this.#ws.onclose = (event) => {
       this.logger.debug(`WebSocket closed: ${event.code} ${event.reason}`);

package/index.ts

@@ -292,6 +292,11 @@ export interface SubspaceDeclaration {
   repo: string;
   /** Apps this subspace serves. Libraries are never listed — they are derived from each app's closure. */
   apps: string[];
+  /**
+   * The cloud workspace this subspace deploys from — its own `AKAN_WORKSPACE_ID`, not this workspace's.
+   * `akan subspace upload-env` is the only thing that reads it.
+   */
+  workspaceId?: string;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-beta.10",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/di/diLifecycle.ts

@@ -17,7 +17,7 @@ import { agentTurnConstant, agentTurnDocument } from "../../signal/agentTurn";
 import { Base, BaseEndpoint, BaseInternal } from "../../signal/base.signal";
 import type { Endpoint } from "../../signal/endpoint";
 import type { Internal } from "../../signal/internal";
-import { Logging, type MiddlewareCls } from "../../signal/middleware";
+import { Cache, Logging, type MiddlewareCls, Timeout } from "../../signal/middleware";
 import type { ServerSignal, ServerSignalCls } from "../../signal/serverSignal";
 import { SignalRegistry } from "../../signal/signalRegistry";
 import type { AkanLib, DatabaseModule, ScalarModule, ServiceModule } from "../akanLib";
@@ -126,6 +126,10 @@ export class DiLifecycle {
       : null;
     if (frameworkAgent) this.#service.set("agent", frameworkAgent);
     this.#middleware.set(Logging.refName, Logging);
+
+    this.#middleware.set(Timeout.refName, Timeout);
+
+    this.#middleware.set(Cache.refName, Cache);
     const defaultOption = createDefaultAkanOption();
     defaultOption.getMiddlewares().forEach((middleware) => {
       this.#middleware.set(middleware.refName, middleware);

package/service/agent.service.ts

@@ -2,6 +2,7 @@ import { Err } from "akanjs/dictionary";
 import type {
   AgentWireAttachment,
   AgentWireMessage,
+  AgentWireReference,
   LlmAccepts,
   LlmTurnRequest,
 } from "./predefinedAdaptor/llm.adaptor";
@@ -16,7 +17,9 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
 
     const names = ToolNames.of(request);
     const prepared = names.encode(
-      AgentService.instructed(AgentService.readable(AgentService.explained(request), this.llm.accepts)),
+      AgentService.instructed(
+        AgentService.readable(AgentService.referenced(AgentService.explained(request)), this.llm.accepts),
+      ),
     );
     const answer = await this.llm.chat(prepared, onDelta);
     if (!answer) throw new Err("agent.error.llmUnavailable");
@@ -68,6 +71,94 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     return { ...rest, text: [message.text, `[The turn failed: ${error}]`].filter(Boolean).join("\n\n") };
   }
 
+  /**
+   * The ceiling one reference's value may add to a turn, mirroring the client's own — the browser clips before it
+   * stages, and this is the same answer given again where nothing can route around it. `runTurn` is the only path
+   * to `chat()`, so a host that builds the wire itself, an older client, and a replayed transcript all pass here.
+   */
+  static readonly referenceLimit = 20_000;
+
+  /**
+   * Folds what the user pointed at into the message they pointed with, as text.
+   *
+   * Text rather than a carrier of its own for the same reason the note in `readable` is text: it is the one field
+   * every provider mapping already reads, so Anthropic, the OpenAI dialect and DeepSeek need no change between
+   * them and none of them can drop a reference quietly.
+   *
+   * The heading rides once per message rather than once per reference, and lives here rather than in `preamble`
+   * because most conversations never carry one — a sentence about mention tokens in every turn of every app is
+   * paid by every app that has no references at all.
+   */
+  static referenced(request: LlmTurnRequest): LlmTurnRequest {
+    if (!request.messages.some((message) => message.references?.length)) return request;
+    return { ...request, messages: request.messages.map((message) => AgentService.referencedMessage(message)) };
+  }
+
+  private static referencedMessage(message: AgentWireMessage): AgentWireMessage {
+    const { references = [], ...rest } = message;
+    if (!references.length) return message;
+    const block = [AgentService.referenceHeading, ...references.map(AgentService.referenceLine)].join("\n\n");
+    return { ...rest, text: [message.text, block].filter(Boolean).join("\n\n") };
+  }
+
+  /**
+   * Not decoration, and not free to shorten. Both halves of the sentence were observed doing their job, against
+   * Anthropic, with the same referenced field and only the published tools changed:
+   *
+   * - With no tool on the screen to re-read with, the model opened its answer by saying so — that it could see
+   *   only the snapshot and the field might have been edited since. Unprompted, ahead of the answer.
+   * - With the screen's own tools passed (a state read and a write), it issued the read instead of answering,
+   *   and stopped the turn there.
+   *
+   * So it reads as an instruction rather than as framing: it re-reads where it can and says it cannot where it
+   * cannot, which is the pair a turn confidently quoting a stale value is bought against. Two scenarios against
+   * one provider, not the per-cell runs behind `preamble` — enough to keep the sentence, not enough to call it
+   * measured.
+   */
+  static readonly referenceHeading =
+    "[Referenced data: the user pointed at this while writing the message above, with the @[label](mention:…) " +
+    "tokens in it. Each value is what it was at the moment they sent the message, not what it is now — read it " +
+    "again with a tool before relying on it, and do not assume an edit you have made since is reflected here.]";
+
+  /**
+   * A string value is printed as itself rather than as JSON. It is the common case — one field of one document —
+   * and a quoted, escaped copy of a paragraph is harder for a model to read back and to quote from than the
+   * paragraph. It is also what a clipped value already is, so the cut JSON prints as the fragment it is.
+   *
+   * The pointer leads the line rather than riding the wire alone, and that is what the label cannot do. Pointed
+   * at a saved document while a *different* document of the same model sat open on the screen, the model
+   * compared the two ids, said the edit it could make would land on the wrong one, and stopped to ask — with no
+   * write call. Two references sharing a label are still two ids here, so keep the id ahead of the label.
+   */
+  private static referenceLine(reference: AgentWireReference): string {
+    const at = `${reference.refName}/${reference.refId}${reference.path ? `#${reference.path}` : ""}`;
+    const head = `${at} (${reference.label}):`;
+    if (reference.value === undefined)
+      return `${head} [not read: ${reference.note ?? "the value was not carried into this conversation"}]`;
+    const text =
+      typeof reference.value === "string" ? reference.value : (JSON.stringify(reference.value, null, 2) ?? "null");
+    const body =
+      text.length <= AgentService.referenceLimit
+        ? text
+        : `${text.slice(0, AgentService.referenceLimit)}…\n[Clipped at ${AgentService.referenceLimit} characters.]`;
+    return `${head}\n${AgentService.fenced(body)}${reference.note ? `\n[${reference.note}]` : ""}`;
+  }
+
+  /**
+   * Where a value ends. A multi-line one — the usual shape of the prose field somebody points at — otherwise runs
+   * straight into the next reference's heading, and the model reads one value that swallowed the next label.
+   *
+   * The fence grows past the longest backtick run inside the value, which is CommonMark's own answer to the same
+   * problem: a fixed fence is one that a value containing a fence breaks out of, and a value containing a fence is
+   * ordinary here, because the thing being pointed at is often something a person wrote.
+   */
+  private static fenced(text: string): string {
+    const runs = text.match(/`+/g);
+    const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
+    const fence = "`".repeat(Math.max(3, longest + 1));
+    return `${fence}\n${text}\n${fence}`;
+  }
+
   /**
    * Replaces every attachment the provider cannot read with a note naming it, so no adaptor has to think about
    * attachments it does not support and none can lose one quietly. The model has to be *told*, not merely spared:
@@ -98,14 +189,18 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
   private static isReadable(attachment: AgentWireAttachment, accepts: LlmAccepts): boolean {
     if (attachment.text) return true;
     if (!attachment.data && !attachment.url) return false;
+
+    if (typeof attachment.mimeType !== "string") return false;
     return attachment.mimeType.startsWith("image/") ? !!accepts.image : !!accepts.document;
   }
 
   private static note(attachment: AgentWireAttachment): string {
     const why =
-      attachment.data || attachment.url
-        ? "this model cannot read that type"
-        : "its content is no longer available, as a reloaded conversation keeps the name and not the bytes";
+      !attachment.data && !attachment.url
+        ? "its content is no longer available, as a reloaded conversation keeps the name and not the bytes"
+        : typeof attachment.mimeType === "string"
+          ? "this model cannot read that type"
+          : "it names no type it could be read as";
     return `[Attachment not read: ${attachment.name} (${attachment.mimeType}) — ${why}. Tell the user it was not read instead of guessing what it holds, and ask for the text if the answer needs it.]`;
   }
 }