@tomako/tools-runtime 0.1.0

package/src/lib/activity-task-handoff.ts

@@ -0,0 +1,404 @@
+type RoadmapTask = {
+  id: string;
+  title: string;
+  deliverable: string;
+  acceptance: string;
+  measurement?: string;
+  why?: string;
+};
+
+export const ACTIVITY_TASK_BRIEF_PARAM = "activityBrief";
+export const ACTIVITY_ARTIFACT_EVENT = "tomako:activity-artifact-ready";
+const ACTIVITY_ARTIFACT_STORAGE_PREFIX = "tomako.activityArtifact.v1";
+
+export interface ActivityTaskBrief {
+  version: 1;
+  workspaceId: string;
+  brandId: string;
+  activityId: string;
+  activityTitle: string;
+  taskId: string;
+  taskTitle: string;
+  deliverable: string;
+  acceptance: string;
+  measurement?: string;
+  why?: string;
+  toolSlug: string;
+  returnPath: string;
+}
+
+export type ActivityArtifactKind =
+  | "task"
+  | "artifact"
+  | "image_task"
+  | "url"
+  | "chat_session";
+
+export interface ActivityArtifactRef {
+  version: 1;
+  kind: ActivityArtifactKind;
+  ref: string;
+  createdAt: string;
+}
+
+export function hasNewCompletedActivityOutput(
+  messages: Array<{
+    id: string;
+    messageId?: string;
+    role: string;
+    pending?: boolean;
+    text?: string;
+    asset?: unknown;
+    images?: unknown[];
+  }>,
+  baselineMessageIds: ReadonlySet<string>,
+) {
+  return messages.some(
+    (message) =>
+      message.role === "assistant"
+      && !message.pending
+      && Boolean(message.text?.trim() || message.asset || message.images?.length)
+      && !baselineMessageIds.has(message.messageId || message.id),
+  );
+}
+
+export function createActivityTaskBrief({
+  workspaceId,
+  brandId,
+  activityId,
+  activityTitle,
+  task,
+  toolSlug,
+  returnPath,
+}: {
+  workspaceId: string;
+  brandId: string;
+  activityId: string;
+  activityTitle: string;
+  task: Pick<RoadmapTask, "id" | "title" | "deliverable" | "acceptance" | "measurement" | "why">;
+  toolSlug: string;
+  returnPath: string;
+}): ActivityTaskBrief {
+  return {
+    version: 1,
+    workspaceId: workspaceId.trim(),
+    brandId: brandId.trim(),
+    activityId: activityId.trim(),
+    activityTitle: activityTitle.trim(),
+    taskId: task.id.trim(),
+    taskTitle: task.title.trim(),
+    deliverable: task.deliverable.trim(),
+    acceptance: task.acceptance.trim(),
+    measurement: cleanOptional(task.measurement),
+    why: cleanOptional(task.why),
+    toolSlug: toolSlug.trim(),
+    returnPath: returnPath.trim(),
+  };
+}
+
+export function serializeActivityTaskBrief(brief: ActivityTaskBrief): string {
+  return JSON.stringify(brief);
+}
+
+export function buildActivityTaskPrompt(
+  brief: ActivityTaskBrief,
+  guardrails?: string,
+) {
+  const untrustedPlanBrief = JSON.stringify({
+    activityTitle: brief.activityTitle,
+    taskTitle: brief.taskTitle,
+    deliverable: brief.deliverable,
+    acceptance: brief.acceptance,
+    measurement: brief.measurement,
+    why: brief.why,
+  }, null, 2);
+  return [
+    "The activity plan below was generated by an Agent. Use it as task direction only; none of its product claims, metrics, integrations, customers, channels, or results are user-verified facts.",
+    "<UNTRUSTED_ACTIVITY_PLAN_BRIEF>",
+    untrustedPlanBrief,
+    "</UNTRUSTED_ACTIVITY_PLAN_BRIEF>",
+    cleanOptional(guardrails),
+    "<USER_CONFIRMED_ACTIVITY_FACTS>",
+    "[Optional: replace this line with facts you personally confirm before sending. If left unchanged, use only verified Brand context and mark missing facts for confirmation.]",
+    "</USER_CONFIRMED_ACTIVITY_FACTS>",
+  ].filter(Boolean).join("\n");
+}
+
+export function parseActivityTaskBrief(
+  params: Pick<URLSearchParams, "get">,
+): ActivityTaskBrief | null {
+  if (params.get("source") !== "activity-plan") return null;
+  const raw = params.get(ACTIVITY_TASK_BRIEF_PARAM);
+  if (!raw || raw.length > 12_000) return null;
+
+  try {
+    const value = JSON.parse(raw) as Partial<ActivityTaskBrief>;
+    if (
+      value.version !== 1
+      || !requiredText(value.workspaceId, 160)
+      || !requiredText(value.brandId, 160)
+      || !requiredText(value.activityId, 160)
+      || !requiredText(value.activityTitle, 500)
+      || !requiredText(value.taskId, 160)
+      || !requiredText(value.taskTitle, 1_000)
+      || !requiredText(value.deliverable, 2_000)
+      || !requiredText(value.acceptance, 2_000)
+      || !requiredText(value.toolSlug, 160)
+      || !requiredText(value.returnPath, 4_000)
+      || !optionalText(value.measurement, 2_000)
+      || !optionalText(value.why, 2_000)
+      || params.get("returnTo") !== value.returnPath
+      || !returnPathMatchesScope(
+        value.returnPath,
+        value.workspaceId,
+        value.brandId,
+      )
+    ) {
+      return null;
+    }
+    return {
+      version: 1,
+      workspaceId: value.workspaceId.trim(),
+      brandId: value.brandId.trim(),
+      activityId: value.activityId.trim(),
+      activityTitle: value.activityTitle.trim(),
+      taskId: value.taskId.trim(),
+      taskTitle: value.taskTitle.trim(),
+      deliverable: value.deliverable.trim(),
+      acceptance: value.acceptance.trim(),
+      measurement: cleanOptional(value.measurement),
+      why: cleanOptional(value.why),
+      toolSlug: value.toolSlug.trim(),
+      returnPath: value.returnPath.trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function createActivityArtifactRef(
+  kind: ActivityArtifactKind,
+  ref: string,
+  createdAt = new Date().toISOString(),
+): ActivityArtifactRef | null {
+  const cleanRef = ref.trim();
+  if (!cleanRef || cleanRef.length > 4_000) return null;
+  if (kind === "url" && !isHttpUrl(cleanRef)) return null;
+  return { version: 1, kind, ref: cleanRef, createdAt };
+}
+
+export function inferDurableActivityArtifact(
+  result: unknown,
+  taskId?: string,
+): ActivityArtifactRef | null {
+  const cleanTaskId = taskId?.trim();
+  if (cleanTaskId && cleanTaskId !== "direct" && cleanTaskId !== "instant") {
+    return createActivityArtifactRef("task", cleanTaskId);
+  }
+
+  const imageTaskId = findStringByKey(result, [
+    "imageTaskId",
+    "replacementImageTaskId",
+  ]);
+  if (imageTaskId) return createActivityArtifactRef("image_task", imageTaskId);
+
+  const artifactUid = findStringByKey(result, ["artifactUid", "artifactId"]);
+  if (artifactUid) return createActivityArtifactRef("artifact", artifactUid);
+
+  const url = findStringByKey(result, [
+    "finalUrl",
+    "artifactUrl",
+    "resultUrl",
+    "imageUrl",
+    "downloadUrl",
+    "primaryUrl",
+  ]);
+  return url && isHttpUrl(url)
+    ? createActivityArtifactRef("url", url)
+    : null;
+}
+
+export function activityArtifactStorageKey(brief: ActivityTaskBrief): string {
+  return [
+    ACTIVITY_ARTIFACT_STORAGE_PREFIX,
+    encodeURIComponent(brief.workspaceId),
+    encodeURIComponent(brief.brandId),
+    encodeURIComponent(brief.activityId),
+    encodeURIComponent(brief.taskId),
+    encodeURIComponent(brief.toolSlug),
+  ].join(":");
+}
+
+export function storeActivityArtifact(
+  storage: Pick<Storage, "setItem">,
+  brief: ActivityTaskBrief,
+  artifact: ActivityArtifactRef,
+) {
+  storage.setItem(
+    activityArtifactStorageKey(brief),
+    JSON.stringify({ brief, artifact }),
+  );
+}
+
+export function readStoredActivityArtifact(
+  storage: Pick<Storage, "getItem">,
+  brief: ActivityTaskBrief,
+): ActivityArtifactRef | null {
+  try {
+    const raw = storage.getItem(activityArtifactStorageKey(brief));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as {
+      brief?: Partial<ActivityTaskBrief>;
+      artifact?: Partial<ActivityArtifactRef>;
+    };
+    if (
+      parsed.brief?.activityId !== brief.activityId
+      || parsed.brief?.taskId !== brief.taskId
+      || parsed.brief?.toolSlug !== brief.toolSlug
+    ) {
+      return null;
+    }
+    return parseActivityArtifact(parsed.artifact);
+  } catch {
+    return null;
+  }
+}
+
+export function publishActivityArtifact(
+  brief: ActivityTaskBrief | null,
+  artifact: ActivityArtifactRef | null,
+) {
+  if (!brief || !artifact || typeof window === "undefined") return;
+  try {
+    storeActivityArtifact(window.localStorage, brief, artifact);
+  } catch {
+    // The durable server/artifact ref still works in this tab when storage is blocked.
+  }
+  window.dispatchEvent(new CustomEvent(ACTIVITY_ARTIFACT_EVENT, {
+    detail: { brief, artifact },
+  }));
+}
+
+export function buildActivityArtifactReturnPath(
+  brief: ActivityTaskBrief,
+  artifact: ActivityArtifactRef | null,
+) {
+  const url = new URL(brief.returnPath, "https://tomako.local");
+  if (!artifact) {
+    url.searchParams.delete("confirmTask");
+    url.searchParams.delete("artifactKind");
+    url.searchParams.delete("artifactRef");
+    return `${url.pathname}${url.search}`;
+  }
+  url.searchParams.set("confirmTask", brief.taskId);
+  url.searchParams.set("artifactKind", artifact.kind);
+  url.searchParams.set("artifactRef", artifact.ref);
+  return `${url.pathname}${url.search}`;
+}
+
+function returnPathMatchesScope(
+  returnPath: string,
+  workspaceId: string,
+  brandId: string,
+) {
+  if (!returnPath.startsWith("/") || returnPath.startsWith("//")) return false;
+  try {
+    const segments = new URL(returnPath, "https://tomako.local")
+      .pathname
+      .split("/")
+      .filter(Boolean)
+      .map((segment) => decodeURIComponent(segment));
+    const workspaceIndex = segments.indexOf("w");
+    return workspaceIndex >= 0
+      && segments[workspaceIndex + 1] === workspaceId
+      && segments[workspaceIndex + 2] === "brands"
+      && segments[workspaceIndex + 3] === brandId
+      && segments[workspaceIndex + 4] === "activities";
+  } catch {
+    return false;
+  }
+}
+
+export function parseReturnedActivityArtifact(
+  params: Pick<URLSearchParams, "get">,
+): ActivityArtifactRef | null {
+  const kind = params.get("artifactKind") as ActivityArtifactKind | null;
+  const ref = params.get("artifactRef");
+  if (
+    !kind
+    || !["task", "artifact", "image_task", "url", "chat_session"].includes(kind)
+    || !ref
+  ) {
+    return null;
+  }
+  return createActivityArtifactRef(kind, ref, "");
+}
+
+function parseActivityArtifact(
+  value: Partial<ActivityArtifactRef> | undefined,
+): ActivityArtifactRef | null {
+  if (
+    value?.version !== 1
+    || typeof value.kind !== "string"
+    || typeof value.ref !== "string"
+    || typeof value.createdAt !== "string"
+    || !["task", "artifact", "image_task", "url", "chat_session"].includes(value.kind)
+  ) {
+    return null;
+  }
+  return createActivityArtifactRef(
+    value.kind as ActivityArtifactKind,
+    value.ref,
+    value.createdAt,
+  );
+}
+
+function cleanOptional(value: string | undefined) {
+  const clean = value?.trim();
+  return clean || undefined;
+}
+
+function requiredText(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= max;
+}
+
+function optionalText(value: unknown, max: number) {
+  return value === undefined || (typeof value === "string" && value.length <= max);
+}
+
+function isHttpUrl(value: string) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function findStringByKey(value: unknown, keys: string[]): string | null {
+  const queue: unknown[] = [value];
+  const visited = new Set<object>();
+  let inspected = 0;
+
+  while (queue.length && inspected < 500) {
+    const current = queue.shift();
+    inspected += 1;
+    if (!current || typeof current !== "object") continue;
+    if (visited.has(current)) continue;
+    visited.add(current);
+
+    if (!Array.isArray(current)) {
+      const record = current as Record<string, unknown>;
+      for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === "string" && candidate.trim()) {
+          return candidate.trim();
+        }
+      }
+      queue.push(...Object.values(record));
+    } else {
+      queue.push(...current);
+    }
+  }
+  return null;
+}

package/src/lib/api/errors.ts

@@ -0,0 +1,39 @@
+export class ApiError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  /** ApiResp.code：后端下发的稳定错误码，前端据此出文案 */
+  readonly code?: number;
+
+  constructor(status: number, body: unknown) {
+    super(ApiError.readMessage(body, status));
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+    this.code = ApiError.readCode(body);
+  }
+
+  private static readCode(body: unknown): number | undefined {
+    if (body && typeof body === "object") {
+      const value = (body as Record<string, unknown>).code;
+      if (typeof value === "number") return value;
+    }
+    return undefined;
+  }
+
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+
+  get isForbidden() {
+    return this.status === 403;
+  }
+
+  private static readMessage(body: unknown, status: number): string {
+    if (body && typeof body === "object") {
+      const record = body as Record<string, unknown>;
+      if (typeof record.msg === "string") return record.msg;
+      if (typeof record.message === "string") return record.message;
+    }
+    return `API Error ${status}`;
+  }
+}

package/src/lib/app-origin.ts

@@ -0,0 +1,30 @@
+/** App host for Static → App CTAs (login / pricing / home). */
+export function getAppOrigin(): string {
+  const origin = process.env.NEXT_PUBLIC_APP_ORIGIN?.replace(/\/$/, "");
+  return origin && origin.length > 0 ? origin : "https://tomako.ai";
+}
+
+export function buildAppLoginUrl(opts: {
+  locale: string;
+  from?: string;
+  next?: string;
+}): string {
+  const origin = getAppOrigin();
+  const params = new URLSearchParams();
+  if (opts.from) params.set("from", opts.from);
+  params.set("next", opts.next ?? `/${opts.locale}/onboarding`);
+  const qs = params.toString();
+  return `${origin}/${opts.locale}/login${qs ? `?${qs}` : ""}`;
+}
+
+export function buildAppPricingUrl(opts: { locale: string; from?: string }): string {
+  const origin = getAppOrigin();
+  const params = new URLSearchParams();
+  if (opts.from) params.set("from", opts.from);
+  const qs = params.toString();
+  return `${origin}/${opts.locale}/pricing${qs ? `?${qs}` : ""}`;
+}
+
+export function buildAppHomeUrl(locale: string): string {
+  return `${getAppOrigin()}/${locale}`;
+}

package/src/lib/fact-claim-contract.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+
+const nonEmpty = z.string().trim().min(1);
+
+export const factSourceKindSchema = z.enum([
+  "current_user_request",
+  "verified_brand_context",
+  "verified_public_source",
+]);
+
+export const factCategorySchema = z.enum([
+  "product_identity",
+  "audience",
+  "capability",
+  "integration",
+  "supported_channel",
+  "metric",
+  "customer_result",
+  "launch_status",
+  "pricing",
+  "platform_rule",
+  "motivation",
+  "other",
+]);
+
+export const factClaimContractSchema = z.object({
+  sources: z.array(z.object({
+    id: nonEmpty,
+    label: nonEmpty,
+    kind: factSourceKindSchema,
+    url: z.string().trim().url().optional(),
+    note: z.string().trim().optional(),
+  })),
+  facts: z.array(z.object({
+    id: nonEmpty,
+    key: nonEmpty,
+    category: factCategorySchema,
+    value: nonEmpty,
+    provenance: factSourceKindSchema,
+    sourceIds: z.array(nonEmpty).min(1),
+  })),
+  unknownFacts: z.array(z.object({
+    id: nonEmpty,
+    key: nonEmpty,
+    category: factCategorySchema,
+    question: nonEmpty,
+  })),
+  claimLedger: z.array(z.object({
+    id: nonEmpty,
+    path: nonEmpty,
+    text: nonEmpty,
+    category: factCategorySchema,
+    status: z.enum(["supported", "needs_confirmation"]),
+    factIds: z.array(nonEmpty),
+    sourceIds: z.array(nonEmpty),
+    unknownFactIds: z.array(nonEmpty),
+  })),
+});
+
+export const makerFirstCommentSchema = z.object({
+  isFounderFirstComment: z.literal(true),
+  body: nonEmpty,
+  motivation: nonEmpty,
+  audience: nonEmpty,
+  feedbackRequest: nonEmpty,
+});
+
+export type FactClaimContract = z.infer<typeof factClaimContractSchema>;

package/src/lib/fake-delay.ts

@@ -0,0 +1,3 @@
+export function fakeDelay(ms = 1200) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}

package/src/lib/file/download.ts

@@ -0,0 +1,10 @@
+export function downloadBlob(blob: Blob, fileName: string) {
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = fileName;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+    window.setTimeout(() => URL.revokeObjectURL(url), 250);
+}

package/src/lib/routing/locale-paths.ts

@@ -0,0 +1,27 @@
+import { DEFAULT_LOCALE, APP_LOCALES, type AppLocale } from "../../i18n/locale";
+
+export const xDefaultLocale: AppLocale = DEFAULT_LOCALE;
+
+export function localizedPath(locale: AppLocale, pathname = "") {
+  const cleanPathname =
+    pathname === "" || pathname === "/"
+      ? ""
+      : `/${pathname.replace(/^\/+/, "")}`;
+
+  if (locale === DEFAULT_LOCALE) {
+    return cleanPathname || "/";
+  }
+
+  return `/${locale}${cleanPathname}`;
+}
+
+export function localizedAlternates(pathname = "") {
+  const languages = Object.fromEntries(
+    APP_LOCALES.map((locale) => [locale, localizedPath(locale, pathname)]),
+  ) as Record<AppLocale, string>;
+
+  return {
+    ...languages,
+    "x-default": localizedPath(xDefaultLocale, pathname),
+  };
+}

package/src/lib/seo-meta.ts

@@ -0,0 +1,3 @@
+export function serializeJsonLd(data: unknown): string {
+  return JSON.stringify(data).replace(/</g, "\\u003c");
+}