@opengeni/worker-bundle 1.0.0-canary.0 → 1.0.0

package/src/activities/agent-turn/skill-save.ts

@@ -41,7 +41,7 @@ export function createSkillSaveAttemptToolDefinition(input: {
     codemodePath: ["opengeni", "skill_save"],
     title: "Save Skill text",
     description:
-      "Create or edit a workspace Skill without a sandbox. Supply only changed UTF-8 text files and explicit deletions; omitted files are preserved. Use the revision and scope version returned by Skill discovery for stale-write protection. For creation choose a new UUID, set expectedRevisionId to null and expectedScopeVersion to 1. The effective Skills setting governs publication: Automatic publishes, Review first saves a pending revision in Knowledge > Needs review while the task continues, and Off prevents agent authoring. Report the actual receipt without asking an approval question. Private chats save personal Skills; shared chats save workspace Skills.",
+      "Create or edit a Skill for reusable procedures or context-specific and personal behavioral preferences, not retrieval-only facts. Put its applicability in the SKILL.md description so the prompt index can guide skill_read; the full body is loaded when relevant. Short always-on workspace rules use instruction_policy_save. Supply only changed UTF-8 text files and explicit deletions; omitted files are preserved. No sandbox is needed. Use the revision and scope version returned by Skill discovery for stale-write protection. For creation choose a new UUID, set expectedRevisionId to null and expectedScopeVersion to 1. The effective Skills setting governs publication: Automatic publishes, Review first saves a pending revision in Knowledge > Needs review while the task continues, and Off prevents agent authoring. Report the actual receipt without asking an approval question. Private chats save personal Skills; shared chats save workspace Skills. Preserve the intended scope; another destination is not a workaround for unavailable scope or learning restrictions.",
     inputSchema: {
       type: "object",
       properties: {

package/src/activities/agent-turn/skill-search.ts

@@ -8,13 +8,15 @@ export type WorkspaceSkillSearchEntry = Readonly<{
   revisionId?: string;
   scopeVersion?: number;
   installationVersion?: number;
-  source?: "workspace" | "builtin" | "session" | "pack";
+  source?: "workspace" | "builtin" | "session";
 }>;
 
 export function createSkillSearchAttemptToolDefinition(input: {
   authorize: () => Promise<void>;
   listWorkspace: () => Promise<readonly WorkspaceSkillSearchEntry[]>;
   publicSearch: PublicSkillSearchClient;
+  /** Ids of the readable Skills a search returned, for read telemetry only. */
+  onWorkspaceHits?: (ids: readonly string[]) => void;
 }): AttemptToolDefinition {
   return {
     identity: { serverId: "opengeni", toolName: "skill_search" },
@@ -59,6 +61,13 @@ export function createSkillSearchAttemptToolDefinition(input: {
           source: entry.source ?? "workspace",
           installed: !entry.source || entry.source === "workspace",
         }));
+      if (workspaceHits.length) {
+        try {
+          input.onWorkspaceHits?.(workspaceHits.map((entry) => entry.id));
+        } catch {
+          // Telemetry never changes a search.
+        }
+      }
       let publicResult: Awaited<ReturnType<PublicSkillSearchClient["search"]>> | null = null;
       let publicError: {
         source: "skills_sh";

package/src/activities/agent-turn/skill-selection.ts

@@ -14,10 +14,13 @@ export function configuredBundledSkillNames(context: BundledSkillConfiguration):
   const tools = new Set(context.firstPartyTools);
   const artifacts = () => tools.has("editable_artifact_list") && tools.has("editable_artifact_get");
   const definitions = [
+    { name: "opengeni-help", include: () => true },
+    { name: "opengeni-client", include: () => true },
     { name: "opengeni-visualize", include: () => true },
     { name: "document-parsing", include: () => true },
     { name: "opengeni-skills", include: () => true },
     { name: "opengeni-projects", include: () => true },
+    { name: "opengeni-schedules", include: () => tools.has("scheduled_tasks_create") },
     { name: "opengeni-documents", include: artifacts },
     { name: "opengeni-spreadsheets", include: artifacts },
     { name: "opengeni-presentations", include: artifacts },
@@ -41,6 +44,7 @@ export function loadConfiguredBundledSkills(context: BundledSkillConfiguration)
   const names = new Set(configuredBundledSkillNames(context));
   const artifacts = loadNativeToolSkillArtifacts({
     projects: names.has("opengeni-projects"),
+    schedules: names.has("opengeni-schedules"),
     editableArtifacts: [
       "opengeni-documents",
       "opengeni-spreadsheets",

package/src/activities/agent-turn/skill-tools.ts

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import type { Settings } from "@opengeni/config";
-import { type SkillActor, type SkillWriteReceipt } from "@opengeni/contracts";
+import { type SkillActor, type SkillScope, type SkillWriteReceipt } from "@opengeni/contracts";
 import {
   assertSkillReadAttempt,
+  getActiveSessionFunctionToolResults,
   skillReviewResolution,
   installPortableSkill,
   replayPortableSkillInstall,
@@ -18,23 +19,35 @@ import {
   readSkill,
   resolveSkillImport,
   saveSkill,
+  removeSkill,
 } from "@opengeni/core";
 import {
   buildPortableSkillArtifact,
   loadSkillLibrarySkill,
+  skillArtifactContentSha256,
   skillLibraryRepositoryUrl,
   type SkillTextFile,
 } from "@opengeni/runtime/skill-library";
 import type { RuntimeSkillArtifact } from "@opengeni/runtime";
-import type { SandboxChannelAService } from "@opengeni/runtime/sandbox";
-import { createSkillReadAttemptToolDefinition, type SkillReadContent } from "./skill-read";
+import {
+  createSkillReadAttemptToolDefinition,
+  SKILL_READ_TOOL_NAME,
+  type SelectedSkillReadContent,
+  type SkillReadContent,
+  type SkillReadObservation,
+  type SkillReadOrigin,
+  unavailableSkillError,
+} from "./skill-read";
 import { createSkillSearchAttemptToolDefinition } from "./skill-search";
 import { createSkillSaveAttemptToolDefinition, type SkillSaveRequest } from "./skill-save";
 import { createSkillInstallAttemptToolDefinition } from "./skill-install";
+import { createSkillRemoveAttemptToolDefinition } from "./skill-remove";
 import {
   createSkillCheckoutAttemptToolDefinition,
   createSkillPublishAttemptToolDefinition,
+  type SkillCheckoutObservation,
 } from "./skill-checkout";
+import type { SkillFileSystem } from "./skill-transfer";
 
 export function createWorkspaceSkillTools(input: {
   db: Database;
@@ -44,9 +57,18 @@ export function createWorkspaceSkillTools(input: {
   subjectId?: string;
   actor: Extract<SkillActor, { kind: "agent" }>;
   selected: readonly { id: string; artifact: RuntimeSkillArtifact }[];
-  filesystem: () => Promise<
-    Pick<SandboxChannelAService, "fsList" | "fsRead" | "fsWrite" | "fsMkdir">
-  >;
+  filesystem: () => Promise<SkillFileSystem>;
+  /** Content-free skill_checkout timing; it never changes a result. */
+  observeSkillCheckout?: (observation: SkillCheckoutObservation) => void;
+  /** The resolved model's bound, which `settings` does not carry. */
+  modelToolOutputTruncationTokens: () => number;
+  onSkillReadHistoryLookupFailed?: (error: unknown) => void;
+  /** Content-free skill_read telemetry; it never changes a result. */
+  skillReadTelemetry?: {
+    /** Ids in the Skill index the model sees this turn; null until known. */
+    indexedSkillIds: () => ReadonlySet<string> | null;
+    observe: (observation: SkillReadObservation) => void;
+  };
 }) {
   const context = {
     accountId: input.accountId,
@@ -55,15 +77,17 @@ export function createWorkspaceSkillTools(input: {
   };
   const authorize = () => assertSkillReadAttempt(input.db, { ...context, actor: input.actor });
   const selected = new Map(input.selected.map((entry) => [entry.id, entry.artifact]));
+  // Readable Skills that skill_search returned in this attempt.
+  const searchedSkillIds = new Set<string>();
   const list = async () =>
     (await listSkillDescriptors(input.db, context)).filter(
       (entry) => entry.activationMode === "workspace_managed",
     );
   // Both text reads and inventory resolve through this same authorized source.
   // Selected artifacts have no ledger revision identity; never synthesize one.
-  const load = async (identifier: string): Promise<readonly SkillTextFile[] | SkillReadContent> => {
+  const load = async (identifier: string): Promise<SkillReadContent | SelectedSkillReadContent> => {
     const exact = selected.get(identifier);
-    if (exact) return exact.files;
+    if (exact) return selectedSkillContent(identifier, exact);
     const descriptors = await list();
     const exactWorkspace = descriptors.find((entry) => entry.id === identifier);
     const matches = exactWorkspace
@@ -76,9 +100,15 @@ export function createWorkspaceSkillTools(input: {
       throw new Error(
         "Multiple Skills match that name. Use the Skill id from the index or search.",
       );
-    if (!matches.length && selectedMatches.length === 1) return selectedMatches[0]![1].files;
+    if (!matches.length && selectedMatches.length === 1)
+      return selectedSkillContent(selectedMatches[0]![0], selectedMatches[0]![1]);
     const match = matches[0];
-    if (!match) throw new Error("Skill is not available in this session.");
+    // skill_checkout resolves through this reader too, so both return the list.
+    if (!match)
+      throw unavailableSkillError(identifier, [
+        ...descriptors.map((entry) => ({ id: entry.id, name: entry.title })),
+        ...[...selected].map(([id, artifact]) => ({ id, name: artifact.name })),
+      ]);
     const record = await readSkill(input.db, context, match.id);
     if (
       !record ||
@@ -95,6 +125,7 @@ export function createWorkspaceSkillTools(input: {
         ? { installationVersion: match.installationVersion }
         : {}),
       files: record.files,
+      origin: { id: record.id, source: registrySkillSource(record.scope) },
     };
   };
   const withReviewState = async (receipt: SkillWriteReceipt) => {
@@ -122,7 +153,39 @@ export function createWorkspaceSkillTools(input: {
     );
   };
   return [
-    createSkillReadAttemptToolDefinition({ authorize, load }),
+    createSkillRemoveAttemptToolDefinition({
+      authorize,
+      remove: async (request) =>
+        withReviewState(
+          await removeSkill(input.db, { ...context, ...request, actor: input.actor }),
+        ),
+    }),
+    createSkillReadAttemptToolDefinition({
+      authorize,
+      load,
+      activeHistory: {
+        readResults: async () =>
+          (
+            await getActiveSessionFunctionToolResults(input.db, {
+              workspaceId: input.workspaceId,
+              sessionId: input.actor.sessionId,
+              toolName: SKILL_READ_TOOL_NAME,
+            })
+          ).map((row) => row.item),
+        toolOutputTruncationTokens: input.modelToolOutputTruncationTokens,
+        ...(input.onSkillReadHistoryLookupFailed
+          ? { onLookupFailed: input.onSkillReadHistoryLookupFailed }
+          : {}),
+      },
+      ...(input.skillReadTelemetry
+        ? {
+            telemetry: {
+              ...input.skillReadTelemetry,
+              searched: (id: string) => searchedSkillIds.has(id),
+            },
+          }
+        : {}),
+    }),
     createSkillSearchAttemptToolDefinition({
       authorize,
       listWorkspace: async () => [
@@ -140,14 +203,13 @@ export function createWorkspaceSkillTools(input: {
           id: entry.id,
           name: entry.artifact.name,
           description: entry.artifact.description || entry.artifact.name,
-          source: entry.id.startsWith("builtin:")
-            ? ("builtin" as const)
-            : entry.id.startsWith("session:")
-              ? ("session" as const)
-              : ("pack" as const),
+          source: entry.id.startsWith("builtin:") ? ("builtin" as const) : ("session" as const),
         })),
       ],
       publicSearch: createPublicSkillSearchClient(input.settings),
+      onWorkspaceHits: (ids) => {
+        for (const id of ids) searchedSkillIds.add(id);
+      },
     }),
     createSkillSaveAttemptToolDefinition({
       authorize,
@@ -241,10 +303,11 @@ export function createWorkspaceSkillTools(input: {
     createSkillCheckoutAttemptToolDefinition({
       authorize,
       filesystem: input.filesystem,
+      ...(input.observeSkillCheckout ? { observe: input.observeSkillCheckout } : {}),
       load: async (skill) => {
         const content = await load(skill);
-        if (!("files" in content))
-          return { skillId: skill, revisionId: null, scopeVersion: null, files: content };
+        if (!("skillId" in content))
+          return { skillId: skill, revisionId: null, scopeVersion: null, files: content.files };
         return content;
       },
     }),
@@ -252,6 +315,37 @@ export function createWorkspaceSkillTools(input: {
   ];
 }
 
+function registrySkillSource(scope: SkillScope): SkillReadOrigin["source"] {
+  return scope === "user" ? "personal" : scope;
+}
+
+// Artifacts are immutable, so each digest is computed once per loaded artifact.
+const selectedArtifactDigests = new WeakMap<RuntimeSkillArtifact, string | null>();
+
+function selectedSkillContent(
+  id: string,
+  artifact: RuntimeSkillArtifact,
+): SelectedSkillReadContent {
+  let digest = selectedArtifactDigests.get(artifact);
+  if (digest === undefined) {
+    try {
+      digest = skillArtifactContentSha256(artifact.files);
+    } catch {
+      // Telemetry identity only; an unhashable artifact still reads.
+      digest = null;
+    }
+    selectedArtifactDigests.set(artifact, digest);
+  }
+  return {
+    files: artifact.files,
+    origin: {
+      id,
+      source: id.startsWith("builtin:") ? "builtin" : "session",
+      ...(digest ? { contentSha256: digest } : {}),
+    },
+  };
+}
+
 function fileMetadata(files: readonly SkillTextFile[]) {
   return files.map((file) => ({
     ...file,

package/src/activities/agent-turn/skill-transfer.ts

@@ -6,10 +6,12 @@ import {
   PORTABLE_SKILL_MAX_FILES,
   PORTABLE_SKILL_MAX_FILE_BYTES,
   PORTABLE_SKILL_MAX_TOTAL_BYTES,
+  SKILL_READ_MAX_PATHS,
+  SkillFileError,
   type SkillTextFile,
 } from "@opengeni/runtime/skill-library";
 
-type SkillFileSystem = Pick<SandboxChannelAService, "fsList" | "fsRead" | "fsWrite" | "fsMkdir">;
+export type SkillFileSystem = Pick<SandboxChannelAService, "fsList" | "fsRead" | "fsWriteFiles">;
 const maxTraversalEntries = 1024;
 
 /** Reuse the host's cancellation and workspace-mutation authority for each filesystem operation. */
@@ -31,36 +33,76 @@ export function guardSkillFilesystem(
   return {
     fsList: (request) => read(() => fs.fsList(request)),
     fsRead: (request) => read(() => fs.fsRead(request)),
-    fsWrite: (request) => write(() => fs.fsWrite(request)),
-    fsMkdir: (request) => write(() => fs.fsMkdir(request)),
+    fsWriteFiles: (request) => write(() => fs.fsWriteFiles(request)),
   };
 }
 
-/** Caller supplies an authorized live filesystem and a fresh workspace-relative target. */
+export type SkillCheckoutResult = {
+  directory: string;
+  fileCount: number;
+  written: number;
+  unchanged: number;
+  /** This call created the directory, so it holds nothing but these files. */
+  createdDirectory: boolean;
+};
+
+/**
+ * Caller supplies an authorized live filesystem and a workspace-relative
+ * target. All missing files are created in one filesystem batch (normally a
+ * single sandbox command). Nothing is overwritten: files already holding the
+ * same bytes are kept, and any other existing entry fails before writing.
+ * `paths` selects exactly those Skill files, for example one script to run.
+ */
 export async function checkoutSkillDirectory(
-  fs: SkillFileSystem,
+  fs: Pick<SkillFileSystem, "fsWriteFiles">,
   directory: string,
   files: readonly SkillTextFile[],
-): Promise<{ directory: string; fileCount: number }> {
+  options: { paths?: readonly string[] } = {},
+): Promise<SkillCheckoutResult> {
   assertSkillRelativePath(directory);
   const artifact = buildPortableSkillArtifact(files);
-  const parent = posix.dirname(directory);
-  if (parent !== ".") await fs.fsMkdir({ path: parent, recursive: true });
-  // Never overwrite an earlier checkout (which may now contain the user's edits).
-  await fs.fsMkdir({ path: directory, recursive: false });
-  for (const file of artifact.files) {
-    const result = await fs.fsWrite({
-      path: `${directory}/${file.path}`,
-      content: file.content,
-      encoding: "utf8",
-      overwrite: false,
-      createParents: true,
-    });
-    if (result.sizeBytes !== new TextEncoder().encode(file.content).byteLength) {
-      throw new Error(`Skill checkout wrote an unexpected byte count: ${file.path}`);
-    }
+  const selected =
+    options.paths === undefined
+      ? artifact.files
+      : selectSkillCheckoutFiles(artifact.files, options.paths);
+  const result = await fs.fsWriteFiles({
+    directory,
+    files: selected.map((file) => ({ path: file.path, content: file.content, encoding: "utf8" })),
+  });
+  if (result.written.length + result.unchanged.length !== selected.length) {
+    throw new Error("Skill checkout returned an incomplete result.");
+  }
+  return {
+    directory,
+    fileCount: selected.length,
+    written: result.written.length,
+    unchanged: result.unchanged.length,
+    createdDirectory: result.createdDirectory,
+  };
+}
+
+function selectSkillCheckoutFiles(
+  files: readonly SkillTextFile[],
+  paths: readonly string[],
+): SkillTextFile[] {
+  if (paths.length === 0 || paths.length > SKILL_READ_MAX_PATHS) {
+    throw new SkillFileError(
+      "invalid_request",
+      `Request between 1 and ${SKILL_READ_MAX_PATHS} paths, or omit paths for the whole Skill.`,
+    );
   }
-  return { directory, fileCount: artifact.files.length };
+  const byPath = new Map(files.map((file) => [file.path, file]));
+  const seen = new Set<string>();
+  return paths.map((path) => {
+    assertSkillRelativePath(path);
+    if (seen.has(path)) {
+      throw new SkillFileError("invalid_request", `Duplicate requested Skill path: ${path}`);
+    }
+    seen.add(path);
+    const file = byPath.get(path);
+    if (!file) throw new SkillFileError("missing_file", `Skill file not found: ${path}`);
+    return file;
+  });
 }
 
 /**
@@ -68,7 +110,10 @@ export async function checkoutSkillDirectory(
  * arguments. The caller owns workspace confinement and the final governed save.
  * This operation does not execute scripts or activate the resulting artifact.
  */
-export async function readSkillDirectory(fs: SkillFileSystem, directory: string) {
+export async function readSkillDirectory(
+  fs: Pick<SkillFileSystem, "fsList" | "fsRead">,
+  directory: string,
+) {
   assertSkillRelativePath(directory);
   const pending = [directory];
   const seen = new Set<string>(pending);