@manta-eu/client 0.1.9 → 0.2.0

package/src/shared/tools/metadata.ts

@@ -0,0 +1,205 @@
+import { humanCount } from "@manta-eu/lib/humanize";
+import { isPresent } from "@manta-eu/lib/present";
+import type { ToolUIPart } from "ai";
+import { match, P } from "ts-pattern";
+import { iriLocalName } from "../rdf-namespaces";
+import type { ToolMetadata, ToolName } from "./types";
+
+export const toolMetadata: ToolMetadata = {
+  getRDFoxFacts: {
+    name: "getRDFoxFacts",
+    category: "rdfox",
+    humanName: "Query knowledge base",
+    description: "Retrieve facts from RDFox knowledge base using SPARQL",
+    getHumanName: (input) => {
+      return input?.humanIntent || "Querying...";
+    },
+  },
+  addRDFoxFacts: {
+    name: "addRDFoxFacts",
+    category: "rdfox",
+    humanName: "Add facts",
+    description: "Add facts to RDFox knowledge base as Turtle",
+    getHumanName: (input) => {
+      return input?.humanIntent || "Adding facts...";
+    },
+  },
+  getRDFoxRules: {
+    name: "getRDFoxRules",
+    category: "rdfox",
+    humanName: "Check rules",
+    description:
+      "Retrieve Datalog rules from RDFox with optional filters (named graph, rdf:type, limit) to avoid context overflow",
+    getHumanName: (input) => {
+      const parts: string[] = [];
+      if (input?.namedGraphIri) parts.push(`plan: ${input.namedGraphIri}`);
+      if (isPresent(input?.rdfTypes)) parts.push(`types: ${input.rdfTypes.join(", ")}`);
+      if (!isPresent(parts)) return "Checking rules...";
+      return `Checking rules ${parts.join(" + ")}`;
+    },
+  },
+  explainRDFoxRules: {
+    name: "explainRDFoxRules",
+    category: "rdfox",
+    humanName: "Explain reasoning",
+    description: "Explain how facts are derived using rules",
+    getHumanName: () => "Explaining reasoning...",
+  },
+  scheduleTask: {
+    name: "scheduleTask",
+    category: "scheduler",
+    humanName: "Schedule task",
+    description: "Schedule a task for future execution",
+    getHumanName: (input) => {
+      return input?.description ? `Schedule: ${input.description}` : "Scheduling...";
+    },
+  },
+  listScheduledTasks: {
+    name: "listScheduledTasks",
+    category: "scheduler",
+    humanName: "List scheduled tasks",
+    description: "List all scheduled tasks",
+    getHumanName: () => "List scheduled tasks",
+  },
+  cancelSchedule: {
+    name: "cancelSchedule",
+    category: "scheduler",
+    humanName: "Cancel task",
+    description: "Cancel a scheduled task",
+    getHumanName: (input) => {
+      return input?.id ? `Cancel task: ${input.id}` : "Canceling task...";
+    },
+  },
+  generateChart: {
+    name: "generateChart",
+    category: "charts",
+    humanName: "Generate chart",
+    description: "Create interactive charts for data visualization",
+    getHumanName: (input) => {
+      return input?.title ? `Chart: ${input.title}` : "Charting...";
+    },
+  },
+  executeActionPlan: {
+    name: "executeActionPlan",
+    category: "action",
+    humanName: "Execute action plan",
+    description: "Execute semantic action plans with SHACL validation and multi-platform orchestration",
+    getHumanName: (input) => {
+      return input?.namedGraphIri ? `Execute plan: ${input.namedGraphIri}` : "Executing action plan...";
+    },
+  },
+  manageRDFoxRules: {
+    name: "manageRDFoxRules",
+    category: "rdfox",
+    humanName: "Manage rules",
+    description: "Add, change, or remove Datalog rules in RDFox knowledge base",
+    getHumanName: (input) => {
+      return input?.humanIntent || "Managing rules...";
+    },
+  },
+  manageRDFoxFacts: {
+    name: "manageRDFoxFacts",
+    category: "rdfox",
+    humanName: "Manage facts",
+    description: "Add, change facts in RDFox knowledge",
+    getHumanName: (input) => {
+      return input?.humanIntent || "Managing facts...";
+    },
+  },
+  actionPlanShowcase: {
+    name: "actionPlanShowcase",
+    category: "action",
+    humanName: "Show action plan",
+    description: "Display a summary card for an action plan with steps and navigation CTA",
+    getHumanName: (input) => {
+      if (input?.actionPlanIRI) {
+        const fragment = iriLocalName(input.actionPlanIRI);
+        return fragment ? `Showcasing plan: ${fragment}` : "Showing action plan...";
+      }
+      return "Showing action plan...";
+    },
+  },
+  showEntities: {
+    name: "showEntities",
+    category: "action",
+    humanName: "Show entities",
+    description: "Display one or several knowledge-graph entities inline in one call",
+    getHumanName: (input) => {
+      if (!isPresent(input?.entityIris)) return "Showing entities...";
+      return `Showing: ${humanCount(input.entityIris.length, "entity")}`;
+    },
+  },
+  checkAutoPilotStatus: {
+    name: "checkAutoPilotStatus",
+    category: "auto-pilot",
+    humanName: "Check auto-pilot status",
+    description: "Check whether auto-pilot is enabled and review cadence and execution history",
+    getHumanName: (input) => input?.humanIntent || "Checking auto-pilot status...",
+  },
+  setDailyChangeLimit: {
+    name: "setDailyChangeLimit",
+    category: "auto-pilot",
+    humanName: "Set daily limit",
+    description: "Change how many actions of an action plan's kinds may start per day",
+    getHumanName: (input) => input?.humanIntent || "Updating daily limit...",
+  },
+  markAsLowRisk: {
+    name: "markAsLowRisk",
+    category: "auto-pilot",
+    humanName: "Mark as low-risk",
+    description: "Mark an action plan as trusted, so a rule may arm auto-pilot on it",
+    getHumanName: (input) => input?.humanIntent || "Marking plan as low-risk...",
+  },
+  readUploadedFile: {
+    name: "readUploadedFile",
+    category: "action",
+    humanName: "Read attachment",
+    description: "Read the contents of a file the user uploaded to this conversation",
+    getHumanName: () => "Reading attachment...",
+  },
+} satisfies ToolMetadata;
+
+export function getToolMetadata<T extends ToolName>(toolName: T): ToolMetadata[T] {
+  return toolMetadata[toolName];
+}
+
+export type GetHumanToolNameInput<T extends ToolName> = Parameters<ToolMetadata[T]["getHumanName"]>[0];
+
+export function getHumanToolName<T extends ToolName>(toolName: T, input?: Record<string, unknown>): string {
+  const metadata = getToolMetadata(toolName);
+  return metadata.getHumanName(input as GetHumanToolNameInput<T>);
+}
+
+export function isValidToolName(toolName: string): toolName is ToolName {
+  return Object.prototype.hasOwnProperty.call(toolMetadata, toolName);
+}
+
+export function getSkillToolLabel(toolUIPart: ToolUIPart): string | undefined {
+  return match(toolUIPart)
+    .with({ type: "tool-activate_skill", input: { name: P.string } }, ({ input }) => `Reading skill: ${input.name}`)
+    .with({ type: "tool-activate_skill" }, () => "Reading skill...")
+    .with(
+      { type: "tool-read_skill_resource", input: { path: P.string } },
+      ({ input }) => `Reading resource: ${input.path}`,
+    )
+    .with({ type: "tool-read_skill_resource" }, () => "Reading resource...")
+    .otherwise(() => undefined);
+}
+
+export function getToolUIPartLabel(toolUIPart: ToolUIPart): string {
+  const skillLabel = getSkillToolLabel(toolUIPart);
+  if (skillLabel) return skillLabel;
+
+  const toolName = toolUIPart.type.replace("tool-", "");
+  if (!isValidToolName(toolName)) return toolName;
+  const input = toolUIPart.input as Record<string, unknown> | undefined;
+  return input ? getHumanToolName(toolName, input) : getToolMetadata(toolName).humanName;
+}
+
+export function assertValidToolName(toolName: string): asserts toolName is ToolName {
+  if (!isValidToolName(toolName)) {
+    throw new Error(`Unknown tool: ${toolName}. Add it to shared/tools/types.ts and metadata.ts`);
+  }
+}
+
+export const allToolNames: readonly ToolName[] = Object.keys(toolMetadata) as ToolName[];

package/src/shared/tools/test-triple.ts

@@ -0,0 +1,33 @@
+import { z } from "zod/v4";
+
+const iriValueSchema = z.string().min(1).describe("Full HTTP(S) or known prefixed IRI, without SPARQL brackets");
+
+const iriObjectInputSchema = z.object({
+  type: z.literal("iri"),
+  value: iriValueSchema,
+});
+
+const languageTagPattern = /^[A-Za-z]+(?:-[A-Za-z0-9]+)*$/;
+
+const literalTermInputSchema = z
+  .object({
+    type: z.literal("literal"),
+    value: z.string().describe("Literal lexical value, without SPARQL quotes"),
+    datatype: z.string().min(1).optional().describe("Optional full or known prefixed datatype IRI"),
+    language: z
+      .string()
+      .regex(languageTagPattern, "Invalid language tag")
+      .optional()
+      .describe("Optional BCP 47 language tag"),
+  })
+  .refine(({ datatype, language }) => !(datatype && language), {
+    message: "A literal cannot have both datatype and language",
+  });
+
+export const testTripleInputSchema = z.object({
+  subject: iriValueSchema.describe("Expected triple subject IRI"),
+  predicate: iriValueSchema.describe("Expected triple predicate IRI"),
+  object: z.discriminatedUnion("type", [iriObjectInputSchema, literalTermInputSchema]),
+});
+
+export type TestTripleInput = z.infer<typeof testTripleInputSchema>;

package/src/shared/tools/types.ts

@@ -0,0 +1,302 @@
+import type { DatalogRule, InferenceVerificationResult } from "@manta-eu/datalog-parser";
+import type { z } from "zod/v4";
+import type { TestTripleInput } from "./test-triple";
+import type { JsonLdGraphDocument } from "#types/jsonld";
+import type { SparqlBinding, SparqlJsonResults } from "#types/sparql-types";
+
+export type { SparqlBinding, SparqlJsonResults, SparqlValue } from "#types/sparql-types";
+export type { TestTripleInput };
+
+export type SparqlJsonBinding = SparqlBinding;
+
+export type ToolName =
+  | "getRDFoxFacts"
+  | "addRDFoxFacts"
+  | "getRDFoxRules"
+  | "explainRDFoxRules"
+  | "scheduleTask"
+  | "listScheduledTasks"
+  | "cancelSchedule"
+  | "generateChart"
+  | "executeActionPlan"
+  | "manageRDFoxRules"
+  | "manageRDFoxFacts"
+  | "actionPlanShowcase"
+  | "showEntities"
+  | "checkAutoPilotStatus"
+  | "setDailyChangeLimit"
+  | "markAsLowRisk"
+  | "readUploadedFile";
+
+export type ToolCategory = "rdfox" | "scheduler" | "charts" | "action" | "auto-pilot";
+
+export type ToolInputSchema<T = unknown> = z.ZodSchema<T>;
+
+export type ToolOutput<T = unknown> = T | ToolErrorResult;
+
+export type ToolErrorResult = {
+  is_error: true;
+  content: string;
+};
+
+export type RDFoxFactsInput = {
+  humanIntent: string;
+  sparql: string;
+  keepPrefixes?: boolean;
+};
+
+export type RDFoxFactsOutput = JsonLdGraphDocument | SparqlJsonResults | ToolErrorResult;
+
+export type AddRDFoxFactsInput = {
+  facts: string;
+  humanIntent: string;
+};
+
+export type AddRDFoxFactsOutput = string | ToolErrorResult;
+
+export type GetRDFoxRulesInput = {
+  namedGraphIri?: string;
+  rdfTypes?: string[];
+  limit?: number;
+};
+
+export type GetRDFoxRulesOutputSuccess = {
+  rules: string[] | string | Record<string, unknown>[]; // TODO: standardize on RuleInfo type
+  totalCount: number;
+  truncated?: boolean;
+};
+
+export type GetRDFoxRulesOutput = GetRDFoxRulesOutputSuccess | ToolErrorResult;
+
+export type ExplainRDFoxRulesInput = {
+  subject: string;
+  predicate?: string;
+  object: string;
+};
+
+export type ToolObjectOutput = object | ToolErrorResult;
+
+export type ExplainRDFoxRulesOutput = ToolObjectOutput;
+
+export type ScheduleTaskInput = {
+  when: "scheduled" | "delayed" | "cron";
+  description: string;
+  [key: string]: unknown;
+};
+
+export type ScheduleTaskOutput = ToolObjectOutput;
+
+export type ListScheduledTasksInput = Record<string, never>;
+
+export type ListScheduledTasksOutput = Array<object> | ToolErrorResult;
+
+export type CancelScheduleInput = {
+  id: string;
+};
+
+export type CancelScheduleOutput = ToolObjectOutput;
+
+export type GenerateChartInputData = {
+  x?: string | number;
+  y?: number;
+  name?: string;
+  value?: number;
+  subject?: string;
+  barValue?: number;
+  lineValue?: number;
+};
+
+export type GenerateChartType = "line" | "area" | "bar" | "pie" | "scatter" | "radar" | "composed";
+
+export type GenerateChartInput = {
+  type: GenerateChartType;
+  title?: string;
+  data: GenerateChartInputData[];
+  height?: number;
+  xAxisLabel?: string;
+  yAxisLabel?: string;
+  barLabel?: string;
+  lineLabel?: string;
+};
+
+export type GenerateChartOutput = {
+  type: "chart";
+  chartType: GenerateChartType;
+  data: object;
+  message: string;
+};
+
+export type ExecuteActionPlanInput = {
+  namedGraphIri: string;
+  shaclShapeIri?: string;
+  dryRun?: boolean;
+  autoApprove?: boolean;
+};
+
+export type ExecuteActionPlanOutput =
+  | {
+      planValidation?: {
+        valid: boolean;
+        completeness: number;
+        issues?: string[];
+      };
+      semanticDiff?: {
+        creates: number;
+        updates: number;
+        deletes: number;
+        operations: unknown[];
+      };
+      workflowId?: string;
+      data?: unknown;
+    }
+  | ToolErrorResult;
+
+export type ManageRDFoxRulesInput = {
+  humanIntent: string;
+  operation: "add" | "change" | "remove";
+  ruleIri?: string;
+  newRule?: string;
+  testTriple?: TestTripleInput;
+  expectNoInference?: boolean;
+  dryRun?: boolean;
+  stageOnly?: boolean;
+};
+export type ManageRDFoxRulesSuccess = {
+  success: true;
+  ruleIri: string;
+  parsedRule: DatalogRule | null;
+  content: string;
+};
+
+export type ManageRDFoxRulesOutput =
+  | (ManageRDFoxRulesSuccess & { dryRun: true })
+  | (ManageRDFoxRulesSuccess & { staged: true })
+  | (ManageRDFoxRulesSuccess & {
+      ruleText: string;
+      inferenceVerified: boolean;
+      inferenceVerification: InferenceVerificationResult | null;
+      commitSummary: {
+        rulesAdded: number;
+        rulesUpdated: number;
+        rulesDeleted: number;
+      };
+    })
+  | ToolErrorResult;
+
+export type ManageRDFoxFactsInput = {
+  humanIntent: string;
+  facts: string;
+  namedGraphIri?: string;
+  operation?: "add" | "update";
+  etag?: string;
+};
+
+export type ManageRDFoxFactsOutput =
+  | {
+      content: string;
+      is_error: boolean;
+    }
+  | ToolErrorResult;
+
+export type ActionPlanStatus = "DRAFT" | "RUNNING" | "COMPLETED" | "FAILED" | "TIMED_OUT";
+
+export type ActionPlanShowcaseInput = {
+  actionPlanIRI: string;
+};
+
+export type ActionPlanShowcaseOutput =
+  | {
+      planIri: string;
+      planName: string;
+      status: ActionPlanStatus;
+    }
+  | ToolErrorResult;
+
+export type ShowEntitiesInput = {
+  entityIris: string[];
+};
+
+export type ShowEntitiesOutput =
+  | {
+      entityIris: string[];
+      graph: JsonLdGraphDocument;
+      message?: string;
+    }
+  | ToolErrorResult;
+
+export type ReadUploadedFileInput = {
+  fileIri: string;
+};
+
+export type ReadUploadedFileOutput = string | ToolErrorResult;
+
+export type ToolDefinition<TInput = unknown, _TOutput = unknown> = {
+  name: ToolName;
+  category: ToolCategory;
+  description: string;
+  inputSchema: ToolInputSchema<TInput>;
+  humanName: string;
+  getHumanName: (input?: TInput) => string;
+};
+
+export type AutoPilotInput = {
+  humanIntent: string;
+  planId: string;
+};
+
+export type SetDailyChangeLimitInput = AutoPilotInput & { dailyChangeLimit?: number };
+
+export type AutoPilotActionPlan = {
+  namedGraphIri: string;
+  autoPilotEnabled?: boolean | null;
+  scheduledCadence?: string | null;
+  scheduledCron?: string | null;
+  scheduleTimezone?: string | null;
+  executionCount?: number | null;
+  lastExecutedAt?: string | null;
+  hasTrustThreshold?: boolean | null;
+  isLowRisk?: boolean | null;
+  maxChangesPerPass?: number | null;
+  dailyChangeLimit?: number | null;
+};
+
+export type AutoPilotOutput = ({ success: true } & AutoPilotActionPlan) | ToolErrorResult;
+
+export type CheckAutoPilotStatusOutput = AutoPilotActionPlan | ToolErrorResult;
+
+export type ToolDefinitions = {
+  getRDFoxFacts: ToolDefinition<RDFoxFactsInput, RDFoxFactsOutput>;
+  addRDFoxFacts: ToolDefinition<AddRDFoxFactsInput, AddRDFoxFactsOutput>;
+  getRDFoxRules: ToolDefinition<GetRDFoxRulesInput, GetRDFoxRulesOutput>;
+  explainRDFoxRules: ToolDefinition<ExplainRDFoxRulesInput, ExplainRDFoxRulesOutput>;
+  scheduleTask: ToolDefinition<ScheduleTaskInput, ScheduleTaskOutput>;
+  listScheduledTasks: ToolDefinition<ListScheduledTasksInput, ListScheduledTasksOutput>;
+  cancelSchedule: ToolDefinition<CancelScheduleInput, CancelScheduleOutput>;
+  generateChart: ToolDefinition<GenerateChartInput, GenerateChartOutput>;
+  executeActionPlan: ToolDefinition<ExecuteActionPlanInput, ExecuteActionPlanOutput>;
+  manageRDFoxRules: ToolDefinition<ManageRDFoxRulesInput, ManageRDFoxRulesOutput>;
+  manageRDFoxFacts: ToolDefinition<ManageRDFoxFactsInput, ManageRDFoxFactsOutput>;
+  actionPlanShowcase: ToolDefinition<ActionPlanShowcaseInput, ActionPlanShowcaseOutput>;
+  showEntities: ToolDefinition<ShowEntitiesInput, ShowEntitiesOutput>;
+  checkAutoPilotStatus: ToolDefinition<AutoPilotInput, CheckAutoPilotStatusOutput>;
+  setDailyChangeLimit: ToolDefinition<SetDailyChangeLimitInput, AutoPilotOutput>;
+  markAsLowRisk: ToolDefinition<AutoPilotInput, AutoPilotOutput>;
+  readUploadedFile: ToolDefinition<ReadUploadedFileInput, ReadUploadedFileOutput>;
+};
+
+export type ToolMetadata = {
+  [K in ToolName]: {
+    name: K;
+    category: ToolCategory;
+    humanName: string;
+    description: string;
+    getHumanName: (
+      input?: ToolDefinitions[K] extends ToolDefinition<infer TInput, unknown> ? TInput : unknown,
+    ) => string;
+  };
+};
+
+export type ToolOutputType<T extends ToolName> =
+  ToolDefinitions[T] extends ToolDefinition<unknown, infer TOutput> ? TOutput : unknown;
+
+export type ToolOutputCoercer<T extends ToolName> = (raw: unknown) => ToolOutputType<T>;

package/src/shared/upload.ts

@@ -0,0 +1,57 @@
+import { getExtension } from "@manta-eu/lib/file";
+import mime from "mime";
+import { MIMEType } from "whatwg-mimetype";
+
+export const uploadPartSize = 8 * 1024 * 1024;
+
+export function bytesToHex(buffer: ArrayBuffer) {
+  return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function sha256Hex(bytes: BufferSource) {
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+
+  return bytesToHex(digest);
+}
+
+export type FileFacts = {
+  byteSize: number;
+  sha256?: string;
+  width?: number;
+  height?: number;
+};
+
+export type UploadedPartEtag = {
+  partNumber: number;
+  etag: string;
+};
+
+export type UploadedFileReference = {
+  fileIri: string;
+  storageKey: string;
+  fileName: string;
+  mediaType: string;
+  byteSize: number;
+};
+
+const maxMediaTypeLength = 255;
+
+export function normalizeMediaType(mediaType: string) {
+  const essence = MIMEType.parse(mediaType)?.essence ?? "";
+
+  return essence.length > maxMediaTypeLength ? "" : essence;
+}
+
+export const maxFileNameBytes = 255;
+
+export function isFileNameTooLong(fileName: string) {
+  return new TextEncoder().encode(fileName).length > maxFileNameBytes;
+}
+
+export function mediaTypeFromExtension(extension: string | undefined) {
+  return (extension ? mime.getType(extension) : undefined) ?? "application/octet-stream";
+}
+
+export function mediaTypeFromFileName(fileName: string) {
+  return mediaTypeFromExtension(getExtension(fileName));
+}

package/src/shared/website-url.ts

@@ -0,0 +1,32 @@
+import { isPresent } from "@manta-eu/lib/present";
+
+export function withHttpsScheme(raw: string): string {
+  const trimmed = raw.trim();
+  return /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+}
+
+// Not round-tripped through URL, which would append a path the graph's existing subjects lack.
+export function websiteUrl(raw: string | null | undefined): string | undefined {
+  if (!isPresent(raw?.trim())) return undefined;
+  return withHttpsScheme(raw);
+}
+
+export function validWebsiteUrl(raw: string | null | undefined): string | undefined {
+  const candidate = websiteUrl(raw);
+  if (!isPresent(candidate)) return undefined;
+
+  try {
+    const url = new URL(candidate);
+    return url.protocol === "http:" || url.protocol === "https:" ? url.toString() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function websiteHost(raw: string): string {
+  try {
+    return new URL(withHttpsScheme(raw)).hostname.replace(/^www\./, "");
+  } catch {
+    return raw;
+  }
+}

package/src/shared/workspace-artifacts.ts

@@ -0,0 +1,68 @@
+import { z } from "zod/v4";
+import { chatIdSchema, chatManagerBasePath, thinkChatFacetPath } from "./chat-manager";
+import { normalizeMediaType } from "./upload";
+
+// Changing this value requires `pnpm db:generate:chat-think` so the SQLite CHECK constraint stays in sync.
+export const workspaceArtifactMaxByteSize = 1_500_000;
+const workspaceArtifactRoutePrefix = `/${chatManagerBasePath}/sub/${thinkChatFacetPath}/`;
+const workspaceArtifactInlineMediaTypes: ReadonlySet<string> = new Set([
+  "image/avif",
+  "image/gif",
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+]);
+
+export function isWorkspaceArtifactInlineMediaType(mediaType: string): boolean {
+  return workspaceArtifactInlineMediaTypes.has(mediaType);
+}
+
+export const workspaceArtifactIdSchema = z.uuid();
+
+function isWorkspaceArtifactUrl(input: { artifactId: string; url: string }): boolean {
+  if (!input.url.startsWith(workspaceArtifactRoutePrefix)) return false;
+
+  const segments = input.url.slice(workspaceArtifactRoutePrefix.length).split("/");
+  if (segments.length !== 3) return false;
+
+  const [encodedConversationId, artifactMarker, artifactId] = segments;
+  if (artifactMarker !== "artifacts" || artifactId !== input.artifactId) {
+    return false;
+  }
+
+  try {
+    return chatIdSchema.safeParse(decodeURIComponent(encodedConversationId ?? "")).success;
+  } catch {
+    return false;
+  }
+}
+
+export const workspaceArtifactSchema = z
+  .strictObject({
+    type: z.literal("workspace-artifact"),
+    artifactId: workspaceArtifactIdSchema,
+    filename: z.string().trim().min(1).max(255),
+    mediaType: z
+      .string()
+      .min(1)
+      .max(255)
+      .refine((mediaType) => normalizeMediaType(mediaType) === mediaType, {
+        message: "Media type must be a normalized MIME essence",
+      }),
+    byteSize: z.number().int().nonnegative().max(workspaceArtifactMaxByteSize),
+    url: z.string(),
+  })
+  .refine(isWorkspaceArtifactUrl, {
+    message: "Artifact URL must match its conversation-scoped artifact route",
+    path: ["url"],
+  });
+
+export type WorkspaceArtifact = z.infer<typeof workspaceArtifactSchema>;
+
+export const publishWorkspaceFileInputSchema = z.strictObject({
+  path: z.string().trim().min(1).max(4096),
+});
+
+export function buildWorkspaceArtifactUrl(input: { conversationId: string; artifactId: string }): string {
+  return `${workspaceArtifactRoutePrefix}${encodeURIComponent(input.conversationId)}/artifacts/${input.artifactId}`;
+}