@capybara-hq/kernel 0.1.0-rc.6 → 0.1.0-rc.7

package/dist/skills/skills.schemas.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/**
+ * The fields of `POST /skills` before the either-or refinement: zod 4 cannot `pick` / `omit` a
+ * refined object, so operations build from these and the route validates {@link SkillCreateBody}.
+ */
+export declare const SkillCreateFields: z.ZodObject<{
+    uploadId: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    description: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    shareable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const SkillCreateBody: z.ZodObject<{
+    uploadId: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    description: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    shareable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** `:id` where the route validates it (`@ZParam`). */
+export declare const SkillIdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/** `:id` where the route takes it as is (`@Param`). */
+export declare const SkillPathParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const SkillShareableSchema: z.ZodObject<{
+    shareable: z.ZodBoolean;
+}, z.core.$strict>;
+/** `:id` of `GET /skill-changes/:id` (taken as is). */
+export declare const SkillChangePathParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/** `:agentId` of the agent's skills and invocable skills routes (taken as is). */
+export declare const AgentSkillsListParams: z.ZodObject<{
+    agentId: z.ZodString;
+}, z.core.$strip>;
+export declare const AgentSkillPathParams: z.ZodObject<{
+    agentId: z.ZodString;
+    skillId: z.ZodString;
+}, z.core.$strip>;
+/** `?conversationId=` of `GET /agents/:agentId/invocable-skills`. */
+export declare const InvocableSkillsQuerySchema: z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const SKILL_ROUTES: readonly RouteSchemas[];

package/dist/skills/skills.schemas.js

@@ -0,0 +1,61 @@
+import { isSkillName, SKILL_LIMITS } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { SKILL_WRITE_MAX_BYTES } from "../tools/builtins/skill-write.js";
+/**
+ * The fields of `POST /skills` before the either-or refinement: zod 4 cannot `pick` / `omit` a
+ * refined object, so operations build from these and the route validates {@link SkillCreateBody}.
+ */
+export const SkillCreateFields = z
+    .object({
+    uploadId: z.string().min(1).max(100).optional(),
+    name: z
+        .string()
+        .refine(isSkillName, "name must be 1-64 lowercase letters, digits and single hyphens")
+        .optional(),
+    description: z.string().min(1).max(SKILL_LIMITS.descriptionMaxChars).optional(),
+    body: z.string().max(SKILL_WRITE_MAX_BYTES).optional(),
+    shareable: z.boolean().optional(),
+})
+    .strict();
+export const SkillCreateBody = SkillCreateFields.refine((v) => v.uploadId !== undefined
+    ? v.name === undefined && v.description === undefined && v.body === undefined
+    : v.name !== undefined && v.description !== undefined && v.body !== undefined, "send either { uploadId } or { name, description, body }");
+/** `:id` where the route validates it (`@ZParam`). */
+export const SkillIdParams = z.object({ id: z.string().min(1).max(100) });
+/** `:id` where the route takes it as is (`@Param`). */
+export const SkillPathParams = z.object({ id: z.string().min(1) });
+export const SkillShareableSchema = z.object({ shareable: z.boolean() }).strict();
+/** `:id` of `GET /skill-changes/:id` (taken as is). */
+export const SkillChangePathParams = z.object({ id: z.string().min(1).max(100) });
+/** `:agentId` of the agent's skills and invocable skills routes (taken as is). */
+export const AgentSkillsListParams = z.object({ agentId: z.string().min(1).max(100) });
+export const AgentSkillPathParams = AgentSkillsListParams.extend({
+    skillId: z.string().min(1).max(100),
+});
+/** `?conversationId=` of `GET /agents/:agentId/invocable-skills`. */
+export const InvocableSkillsQuerySchema = z
+    .object({ conversationId: z.string().min(1).max(100).optional() })
+    .strict();
+export const SKILL_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/skill-changes/:id", params: SkillChangePathParams },
+    { route: "GET /api/v1/orgs/:orgId/agents/:agentId/skills", params: AgentSkillsListParams },
+    {
+        route: "DELETE /api/v1/orgs/:orgId/agents/:agentId/skills/:skillId",
+        params: AgentSkillPathParams,
+    },
+    {
+        route: "GET /api/v1/orgs/:orgId/agents/:agentId/invocable-skills",
+        params: AgentSkillsListParams,
+        query: InvocableSkillsQuerySchema,
+    },
+    { route: "GET /api/v1/orgs/:orgId/skills" },
+    { route: "GET /api/v1/orgs/:orgId/skills/:id", params: SkillPathParams },
+    { route: "POST /api/v1/orgs/:orgId/skills", body: SkillCreateBody },
+    {
+        route: "PUT /api/v1/orgs/:orgId/skills/:id/shareable",
+        params: SkillIdParams,
+        body: SkillShareableSchema,
+    },
+    { route: "GET /api/v1/orgs/:orgId/skills/:id/delete-preview", params: SkillIdParams },
+    { route: "DELETE /api/v1/orgs/:orgId/skills/:id", params: SkillPathParams },
+];

package/dist/skills/skills.service.d.ts

@@ -188,6 +188,16 @@ export declare class SkillsService {
      * ({@link createVersionIn} joins it).
      */
     private createUploadedVersionIn;
+    /**
+     * The read-only checks of {@link createFromText}, for the `Platform` tool's precheck (before the
+     * card): custom skills allowed, a valid `SKILL.md`, and no live org skill of the name. Throws the
+     * same `ApiError` the create would; the create checks the name again under its lock.
+     */
+    checkCreateFromText(orgId: string, input: {
+        name: string;
+        description: string;
+        body: string;
+    }): Promise<void>;
     /**
      * Creates an org skill from text (spec §14, P3-24): `SKILL.md` is built from the name,
      * description and body ({@link buildSkillWrite}, the description a YAML string) and checked like
@@ -285,5 +295,5 @@ export declare class SkillsService {
      * (audit `skill.deleted`); missing or deleted -> `skill.not_found`. The owner delete of a
      * promoted skill (`OwnedItems.deleteSkill`) calls it after its platform row was dealt with.
      */
-    deleteOrgSkillIn(orgId: string, skillId: string, actorAccountId: string, actorTokenId: string | undefined): Promise<void>;
+    deleteOrgSkillIn(orgId: string, skillId: string, actorAccountId: string, actorTokenId: string | undefined, auditDetail?: Record<string, unknown>): Promise<void>;
 }

package/dist/skills/skills.service.js

@@ -126,6 +126,19 @@ const PUT_CONCURRENCY = 4;
 /** 详情里读取 SKILL.md 正文的上限。 */
 export const SKILL_BODY_MAX_BYTES = 1024 * 1024;
 const notFound = () => new ApiError("skill.not_found", "Skill not found");
+const nameExists = (name) => new ApiError("skill.name_exists", `A skill named "${name}" already exists in this organization. Choose another name.`);
+/** The checked files of a skill written as text (a built `SKILL.md`); `validation_failed` if not. */
+function textSkillFiles(input) {
+    const built = buildSkillWrite({
+        name: input.name,
+        description: input.description,
+        files: [{ path: SKILL_ENTRY_FILE, content: input.body }],
+    });
+    if ("errors" in built) {
+        throw new ApiError("validation_failed", `Invalid skill: ${built.errors[0] ?? "unknown problem"}`, built.errors.map((message) => ({ path: "body", message })));
+    }
+    return checkBuiltSkillFiles(built.files);
+}
 /**
  * 在调用方事务里核对 agent 定义引用的组织技能：每个 id 都必须是该组织未删除的 `scope=org` 技能
  * (or, phase 2, a platform skill on in the org: skills/usable.ts)，
@@ -449,6 +462,25 @@ let SkillsService = class SkillsService {
             ...(owner !== undefined && { owner }),
         });
     }
+    /**
+     * The read-only checks of {@link createFromText}, for the `Platform` tool's precheck (before the
+     * card): custom skills allowed, a valid `SKILL.md`, and no live org skill of the name. Throws the
+     * same `ApiError` the create would; the create checks the name again under its lock.
+     */
+    async checkCreateFromText(orgId, input) {
+        await assertCustomAllowed(this.db.db, "customSkills");
+        const pkg = textSkillFiles(input);
+        const existing = await this.db
+            .selectFrom("skills")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("scope", "=", "org")
+            .where("name", "=", pkg.name)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (existing)
+            throw nameExists(pkg.name);
+    }
     /**
      * Creates an org skill from text (spec §14, P3-24): `SKILL.md` is built from the name,
      * description and body ({@link buildSkillWrite}, the description a YAML string) and checked like
@@ -458,15 +490,7 @@ let SkillsService = class SkillsService {
     async createFromText(orgId, actorAccountId, input) {
         this.storage.assertAvailable();
         await assertCustomAllowed(this.db.db, "customSkills");
-        const built = buildSkillWrite({
-            name: input.name,
-            description: input.description,
-            files: [{ path: SKILL_ENTRY_FILE, content: input.body }],
-        });
-        if ("errors" in built) {
-            throw new ApiError("validation_failed", `Invalid skill: ${built.errors[0] ?? "unknown problem"}`, built.errors.map((message) => ({ path: "body", message })));
-        }
-        const pkg = checkBuiltSkillFiles(built.files);
+        const pkg = textSkillFiles(input);
         const prefix = skillFilesPrefix(randomUUID());
         await this.putFiles(orgId, prefix, pkg.files);
         return this.createVersionIn(orgId, actorAccountId, pkg, skillManifest(pkg), prefix, {
@@ -533,9 +557,8 @@ let SkillsService = class SkillsService {
             .where("deleted_at", "is", null)
             .forUpdate()
             .executeTakeFirst();
-        if (existing && opts.failIfExists) {
-            throw new ApiError("skill.name_exists", `A skill named "${pkg.name}" already exists in this organization. Choose another name.`);
-        }
+        if (existing && opts.failIfExists)
+            throw nameExists(pkg.name);
         // The org's own skill it promoted (ruling P3-3): its new version goes to the platform row and
         // reaches every org using it (ruling P3-4); the files were written there before this
         // transaction, for the platform version current then
@@ -904,7 +927,7 @@ let SkillsService = class SkillsService {
      * (audit `skill.deleted`); missing or deleted -> `skill.not_found`. The owner delete of a
      * promoted skill (`OwnedItems.deleteSkill`) calls it after its platform row was dealt with.
      */
-    async deleteOrgSkillIn(orgId, skillId, actorAccountId, actorTokenId) {
+    async deleteOrgSkillIn(orgId, skillId, actorAccountId, actorTokenId, auditDetail) {
         const r = await this.db
             .updateTable("skills")
             .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
@@ -922,7 +945,7 @@ let SkillsService = class SkillsService {
             orgId,
             action: "skill.deleted",
             target: skillId,
-            detail: { name: r.name },
+            detail: { name: r.name, ...auditDetail },
         });
     }
 };

package/dist/time-zone.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+/** Whether `tz` is an IANA time zone this runtime knows (run context spec §3.3, §3.4). */
+export declare function isTimeZone(tz: string): boolean;
+/** An IANA time zone name, checked with `Intl.DateTimeFormat`. */
+export declare const IanaTimeZone: z.ZodString;

package/dist/time-zone.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/** Whether `tz` is an IANA time zone this runtime knows (run context spec §3.3, §3.4). */
+export function isTimeZone(tz) {
+    if (tz === "" || tz.length > 64)
+        return false;
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** An IANA time zone name, checked with `Intl.DateTimeFormat`. */
+export const IanaTimeZone = z
+    .string()
+    .min(1)
+    .max(64)
+    .refine(isTimeZone, "must be an IANA time zone name, such as Asia/Shanghai");

package/dist/tools/approvals.controller.js

@@ -14,10 +14,9 @@ import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { CONTROL_OR_HIDDEN_RE } from "../text.js";
+import { ApprovalsListQuerySchema } from "./approvals.schemas.js";
 import { APPROVAL_DENY_REASON_MAX_CHARS, ApprovalsService, } from "./approvals.service.js";
-const ListQuery = z
-    .object({ status: z.enum(["pending", "approved", "denied", "expired", "cancelled"]).optional() })
-    .strict();
+const ListQuery = ApprovalsListQuerySchema;
 const DecisionBody = z
     .object({
     decision: z.enum(["approve", "deny"]),

package/dist/tools/approvals.schemas.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `GET /approvals?status=`: absent lists every status. */
+export declare const ApprovalsListQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        approved: "approved";
+        cancelled: "cancelled";
+        denied: "denied";
+        expired: "expired";
+        pending: "pending";
+    }>>;
+}, z.core.$strict>;
+/** `:id` of `GET /approvals/:id`, as the route takes it (`@Param`). */
+export declare const ApprovalPathParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The approval reads a Platform operation mirrors. Deciding (`POST /approvals/:id/decision`) is a
+ * person's act and stays excluded (spec §6.4, §14.1 item 2), so it has no entry here.
+ */
+export declare const APPROVAL_ROUTES: readonly RouteSchemas[];

package/dist/tools/approvals.schemas.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** `GET /approvals?status=`: absent lists every status. */
+export const ApprovalsListQuerySchema = z
+    .object({ status: z.enum(["pending", "approved", "denied", "expired", "cancelled"]).optional() })
+    .strict();
+/** `:id` of `GET /approvals/:id`, as the route takes it (`@Param`). */
+export const ApprovalPathParams = z.object({ id: z.string() });
+/**
+ * The approval reads a Platform operation mirrors. Deciding (`POST /approvals/:id/decision`) is a
+ * person's act and stays excluded (spec §6.4, §14.1 item 2), so it has no entry here.
+ */
+export const APPROVAL_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/approvals", query: ApprovalsListQuerySchema },
+    { route: "GET /api/v1/orgs/:orgId/approvals/:id", params: ApprovalPathParams },
+];

package/dist/tools/builtin-names.d.ts

@@ -1,4 +1,3 @@
-import type { AgentToolRef } from "../agents/definition.js";
 import type { ToolKind } from "./info.js";
 /**
  * The names (model-visible keys) of the kernel's builtin tools, following Claude Code (tool naming
@@ -28,6 +27,7 @@ export declare const BUILTIN: {
     readonly WebSearch: "WebSearch";
     readonly WebFetch: "WebFetch";
     readonly Platform: "Platform";
+    readonly CurrentTime: "CurrentTime";
 };
 export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
 /**
@@ -49,12 +49,13 @@ export declare const BASH_COMPANION_TOOLS: readonly BuiltinName[];
  */
 export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
 /**
- * Every builtin name. Saving an agent checks builtin refs against this list, not against what is
- * registered now, so the order the implementations land in never affects a saved definition.
- * `SkillWrite` is available only when a definition names it; `ToolSearch` and `Skill` are added
+ * Every builtin name. Saving an agent checks turned-off builtins against this list, not against
+ * what is registered now, so the order the implementations land in never affects a saved
+ * definition. `ToolSearch` and `Skill` are added
  * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
  * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
  * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
+ * `CurrentTime` reads the clock (the run context carries only the date).
  */
 export declare const BUILTIN_TOOL_NAMES: readonly BuiltinName[];
 /** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
@@ -91,11 +92,12 @@ export declare const R3_SHARED_AGENT_ONLY_TOOL_KEYS: ReadonlySet<string>;
  */
 export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver", "SkillWrite"];
 /**
- * The tools of a new agent created without `tools` (`ToolSearch` is added by the registry, never
- * by a definition). Only for create requests; updates and stored versions get no defaults.
- * `Platform` is on by default (Platform tool spec §3: reads are harmless, every write confirmed).
+ * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
+ * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
+ * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop`, which come
+ * with `Bash` ({@link BASH_COMPANION_TOOLS}). These are also the builtins an agent can turn off.
  */
-export declare const DEFAULT_AGENT_TOOLS: AgentToolRef[];
+export declare const AGENT_BUILTIN_NAMES: readonly BuiltinName[];
 /** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
 export declare const BUILTIN_TOOL_KINDS: Readonly<Record<string, ToolKind>>;
 /**

package/dist/tools/builtin-names.js

@@ -26,6 +26,7 @@ export const BUILTIN = {
     WebSearch: "WebSearch",
     WebFetch: "WebFetch",
     Platform: "Platform",
+    CurrentTime: "CurrentTime",
 };
 /**
  * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
@@ -61,12 +62,13 @@ export const SANDBOX_ASK_TOOL_NAMES = new Set([
     BUILTIN.Deliver,
 ]);
 /**
- * Every builtin name. Saving an agent checks builtin refs against this list, not against what is
- * registered now, so the order the implementations land in never affects a saved definition.
- * `SkillWrite` is available only when a definition names it; `ToolSearch` and `Skill` are added
+ * Every builtin name. Saving an agent checks turned-off builtins against this list, not against
+ * what is registered now, so the order the implementations land in never affects a saved
+ * definition. `ToolSearch` and `Skill` are added
  * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
  * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
  * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
+ * `CurrentTime` reads the clock (the run context carries only the date).
  */
 export const BUILTIN_TOOL_NAMES = [
     BUILTIN.AskUserQuestion,
@@ -80,6 +82,7 @@ export const BUILTIN_TOOL_NAMES = [
     BUILTIN.SubagentHandback,
     ...WEB_TOOL_NAMES,
     BUILTIN.Platform,
+    BUILTIN.CurrentTime,
 ];
 /** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
 export const SKILL_LOAD = BUILTIN.Skill;
@@ -124,15 +127,16 @@ export const CHILD_REMOVED_TOOLS = [
     BUILTIN.SkillWrite,
 ];
 /**
- * The tools of a new agent created without `tools` (`ToolSearch` is added by the registry, never
- * by a definition). Only for create requests; updates and stored versions get no defaults.
- * `Platform` is on by default (Platform tool spec §3: reads are harmless, every write confirmed).
+ * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
+ * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
+ * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop`, which come
+ * with `Bash` ({@link BASH_COMPANION_TOOLS}). These are also the builtins an agent can turn off.
  */
-export const DEFAULT_AGENT_TOOLS = [
-    { kind: "builtin", name: BUILTIN.AskUserQuestion },
-    { kind: "builtin", name: BUILTIN.ReadToolOutput },
-    { kind: "builtin", name: BUILTIN.Platform },
-];
+export const AGENT_BUILTIN_NAMES = BUILTIN_TOOL_NAMES.filter((n) => n !== BUILTIN.ToolSearch &&
+    n !== BUILTIN.Skill &&
+    n !== BUILTIN.SendMessage &&
+    n !== BUILTIN.SubagentHandback &&
+    !BASH_COMPANION_TOOLS.includes(n));
 /** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
 export const BUILTIN_TOOL_KINDS = {
     [BUILTIN.Bash]: "command",
@@ -154,6 +158,7 @@ export const BUILTIN_TOOL_KINDS = {
     [BUILTIN.WebSearch]: "search",
     [BUILTIN.WebFetch]: "read",
     [BUILTIN.Platform]: "tool",
+    [BUILTIN.CurrentTime]: "tool",
 };
 /**
  * Input fields left out when matching a replayed call with a recorded one (full-run replay), per

package/dist/tools/builtins/builtin-tools.d.ts

@@ -33,7 +33,9 @@ export declare class BuiltinTools {
     /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
     purposes: ModelPurposesService, host: {
         readonly hooks?: HookRunner;
-    } | undefined, usageReport: UsageReporter, stepLog: StepLog, log: Logger, background: BackgroundTaskStore, finisher: BackgroundTaskFinisher, stopper: BackgroundTaskStopper, platformOps: PlatformOperations, platformActor: PlatformActor, agentDocs: AgentDocs);
+    } | undefined, usageReport: UsageReporter, stepLog: StepLog, log: Logger, background: BackgroundTaskStore, finisher: BackgroundTaskFinisher, stopper: BackgroundTaskStopper, platformOps: PlatformOperations, platformActor: PlatformActor, agentDocs: AgentDocs, 
+    /** The clock `CurrentTime` reads (the run context's clock seam; `Date.now` by default). */
+    now?: () => number);
     /** The builtin tools, in a fixed order. */
     list(): readonly BuiltinTool[];
 }

package/dist/tools/builtins/builtin-tools.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Inject, Injectable } from "@nestjs/common";
+import { Inject, Injectable, Optional } from "@nestjs/common";
 import { BackgroundTaskFinisher } from "../../background/finish.js";
 import { BackgroundTaskStopper } from "../../background/stop.js";
 import { BackgroundTaskStore } from "../../background/store.js";
@@ -24,6 +24,7 @@ import { readOrgSettings } from "../../orgs/settings.service.js";
 import { PlatformActor } from "../../platform/actor.js";
 import { AgentDocs } from "../../platform/agent-docs.js";
 import { PlatformOperations } from "../../platform/registry.js";
+import { conversationTimeZone, RUN_CONTEXT_CLOCK } from "../../runtime/run-context.service.js";
 import { StepLog } from "../../runtime/step-log.js";
 import { UsageReporter } from "../../runtime/usage-report.js";
 import { SandboxService } from "../../sandbox/sandbox.service.js";
@@ -32,6 +33,7 @@ import { StorageService } from "../../storage/storage.service.js";
 import { ToolOutputs } from "../outputs.js";
 import { agentTool } from "./agent.js";
 import { askUserTool } from "./ask-user.js";
+import { currentTimeTool } from "./current-time.js";
 import { handbackTool } from "./handback.js";
 import { platformTool } from "./platform.js";
 import { readToolOutputTool } from "./read-tool-output.js";
@@ -51,7 +53,9 @@ let BuiltinTools = class BuiltinTools {
     tools;
     constructor(db, config, outputs, storage, skillChanges, attachments, eventLog, sandbox, environments, points, webPages, 
     /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
-    purposes, host, usageReport, stepLog, log, background, finisher, stopper, platformOps, platformActor, agentDocs) {
+    purposes, host, usageReport, stepLog, log, background, finisher, stopper, platformOps, platformActor, agentDocs, 
+    /** The clock `CurrentTime` reads (the run context's clock seam; `Date.now` by default). */
+    now) {
         const sandboxDeps = {
             sandbox,
             environments,
@@ -101,6 +105,12 @@ let BuiltinTools = class BuiltinTools {
                 actor: platformActor,
                 docs: agentDocs,
                 setting: async (orgId) => (await readOrgSettings(db.db, orgId)).platformTool,
+                log,
+            }),
+            // the clock in the run context's time zone (the run context carries only the date)
+            currentTimeTool({
+                now: now ?? Date.now,
+                timeZoneOf: ({ orgId, conversationId }) => conversationTimeZone(db.db, orgId, conversationId),
             }),
         ];
     }
@@ -132,6 +142,8 @@ BuiltinTools = __decorate([
     __param(18, Inject(BackgroundTaskStopper)),
     __param(19, Inject(PlatformOperations)),
     __param(20, Inject(PlatformActor)),
-    __param(21, Inject(AgentDocs))
+    __param(21, Inject(AgentDocs)),
+    __param(22, Optional()),
+    __param(22, Inject(RUN_CONTEXT_CLOCK))
 ], BuiltinTools);
 export { BuiltinTools };

package/dist/tools/builtins/current-time.d.ts

@@ -0,0 +1,26 @@
+import type { BuiltinTool } from "../registry.js";
+/** An unknown zone: what was wrong and how to call again. */
+export declare const unknownTimeZoneText: (zone: string) => string;
+/** The local wall clock of `now` in `timeZone`, with its offset from UTC. */
+export interface LocalTime {
+    /** `YYYY-MM-DDTHH:mm:ss±HH:MM`. */
+    local: string;
+    weekday: string;
+    /** `+08:00`, `-05:00`, `+00:00`. */
+    offset: string;
+    /** `YYYY-MM-DDTHH:mm:ssZ`. */
+    utc: string;
+}
+/** Formats `now` in `timeZone` (a zone {@link isTimeZone} accepts). Seconds precision. */
+export declare function localTime(now: Date, timeZone: string): LocalTime;
+export interface CurrentTimeDeps {
+    /** The clock (epoch ms): the kernel's `RUN_CONTEXT_CLOCK` seam, `Date.now` by default. */
+    now: () => number;
+    /** The conversation's time zone (its run context's, else the org default, else UTC). */
+    timeZoneOf: (ctx: {
+        orgId: string;
+        conversationId: string;
+    }) => Promise<string>;
+}
+/** The `CurrentTime` builtin. */
+export declare function currentTimeTool(deps: CurrentTimeDeps): BuiltinTool;

package/dist/tools/builtins/current-time.js

@@ -0,0 +1,99 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { isTimeZone } from "../../time-zone.js";
+import { BUILTIN } from "../builtin-names.js";
+/**
+ * The `CurrentTime` builtin: the current local date-time in a time zone. The run context gives the
+ * model the date only (day granularity, run context spec §3), so the time of day, durations and
+ * other zones come from this tool. Read-only, no side effects: `defaultPolicy` is allow. The
+ * result goes into the log like any tool result, so replays read the recorded answer.
+ */
+const SPEC = {
+    name: BUILTIN.CurrentTime,
+    description: "Get the current time: the local date and time with its UTC offset, the weekday, the time " +
+        "zone and the UTC instant. Today's date is already in your context; call this when you need " +
+        "the time of day, to work out a duration or how long ago something happened, or to know the " +
+        "time in another time zone. Without timeZone it uses the time zone of the person you work " +
+        "for. Read-only, no side effects.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            timeZone: {
+                type: "string",
+                minLength: 1,
+                maxLength: 64,
+                description: "An IANA time zone name, e.g. Asia/Shanghai, America/New_York or UTC. Omit it to use " +
+                    "the time zone of the person you work for.",
+            },
+        },
+        additionalProperties: false,
+    },
+};
+const Input = z.object({ timeZone: z.string().min(1).max(64).optional() }).strict();
+/** An unknown zone: what was wrong and how to call again. */
+export const unknownTimeZoneText = (zone) => `Unknown time zone '${zone}'; use an IANA name such as Asia/Shanghai or America/New_York, ` +
+    "or omit timeZone to use the time zone of the person you work for.";
+/** The input did not parse (the schema check runs first, so this is a guard). */
+const INVALID_INPUT_TEXT = "Invalid input; pass an object with an optional timeZone string (an IANA name such as Asia/Shanghai).";
+const pad = (n, w = 2) => String(n).padStart(w, "0");
+/** Formats `now` in `timeZone` (a zone {@link isTimeZone} accepts). Seconds precision. */
+export function localTime(now, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        weekday: "long",
+        hourCycle: "h23",
+    }).formatToParts(now);
+    const part = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    const [y, mo, d, h, mi, s] = ["year", "month", "day", "hour", "minute", "second"].map((t) => Number(part(t)));
+    const seconds = Math.floor(now.getTime() / 1000) * 1000;
+    // the zone's offset: the wall clock read as if it were UTC, minus the instant
+    const offsetMin = Math.round((Date.UTC(y, mo - 1, d, h, mi, s) - seconds) / 60_000);
+    const abs = Math.abs(offsetMin);
+    const offset = `${offsetMin < 0 ? "-" : "+"}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+    return {
+        local: `${pad(y, 4)}-${pad(mo)}-${pad(d)}T${pad(h)}:${pad(mi)}:${pad(s)}${offset}`,
+        weekday: part("weekday"),
+        offset,
+        utc: `${new Date(seconds).toISOString().slice(0, 19)}Z`,
+    };
+}
+/** The `CurrentTime` builtin. */
+export function currentTimeTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        async run(input, ctx) {
+            const parsed = Input.safeParse(input ?? {});
+            if (!parsed.success)
+                throw new ToolError(INVALID_INPUT_TEXT);
+            const asked = parsed.data.timeZone?.trim();
+            if (asked !== undefined && !isTimeZone(asked)) {
+                throw new ToolError(unknownTimeZoneText(asked));
+            }
+            const zone = asked ?? (await deps.timeZoneOf({ orgId: ctx.orgId, conversationId: ctx.conversationId }));
+            const t = localTime(new Date(deps.now()), zone);
+            const text = `Current time: ${t.local} (${t.weekday})\n` +
+                `Time zone: ${zone} (UTC${t.offset})\n` +
+                `UTC: ${t.utc}`;
+            // the row's key argument already shows a zone the model passed; the summary then gives the
+            // time alone, and names the zone only when it came from the run context
+            const hm = t.local.slice(11, 16);
+            const where = asked === undefined ? { zh: `（${zone}）`, en: ` (${zone})` } : { zh: "", en: "" };
+            return {
+                content: [{ type: "text", text }],
+                display: {
+                    summary: {
+                        zh: `已获取当前时间 · ${hm}${where.zh}`,
+                        en: `Got the current time · ${hm}${where.en}`,
+                    },
+                },
+            };
+        },
+    };
+}