deepline 0.3.460 → 0.3.462

package/dist/cli/{chunk-CTRPCARW.mjs → chunk-7U3XNPOA.mjs}

@@ -1,11 +1,12 @@
 import {
   addDescribeOptions,
-  recordApiResponse
-} from "./chunk-YBWAG72P.mjs";
+  recordApiResponse,
+  writeExecutionOutput
+} from "./chunk-FKVYR3QA.mjs";
 import {
   recentSearchRef,
   registerDeprecatedSearchCommand
-} from "./chunk-LVJOFUU7.mjs";
+} from "./chunk-MUUQZIOF.mjs";
 import {
   arrayField,
   formatModelDescription,
@@ -24,10 +25,10 @@ import {
   toolInputFieldsForDisplay,
   toolMetadataJsonForDescribe,
   toolOutputFieldsForDisplay
-} from "./chunk-SLEUWLJE.mjs";
+} from "./chunk-MSY22NQW.mjs";
 import {
   rateLimitQualifier
-} from "./chunk-HDFRJ4IT.mjs";
+} from "./chunk-JVHOS3K3.mjs";
 import {
   shellQuote
 } from "./chunk-OVDNJAJN.mjs";
@@ -46,9 +47,11 @@ import {
   writeJsonOutputFile
 } from "./chunk-FIVKWNMT.mjs";
 import {
-  DeeplineClient,
+  DeeplineClient
+} from "./chunk-7MJ6VI2T.mjs";
+import {
   validateExecutionIdempotencyKey
-} from "./chunk-ZR2RLI4O.mjs";
+} from "./chunk-UDRPEZ5F.mjs";
 import {
   stableStringify
 } from "./chunk-UBKA33KY.mjs";
@@ -58,18 +61,18 @@ import {
   maybeAutoUpdateAndRelaunch,
   registerCompatibilityCatalog,
   runToolExecuteStage
-} from "./chunk-W3BE3CHK.mjs";
+} from "./chunk-O2RX5A66.mjs";
 import {
   isCliTraceEnabled,
   recordCliTrace,
   resolveCliMaintenancePolicy
-} from "./chunk-LAWEURCT.mjs";
+} from "./chunk-LFXLQEZN.mjs";
 import {
   checkSdkCompatibility,
   enforceSdkCompatibilityResponse,
   flushDeferredSkillsSyncNotices,
   syncSdkSkillsIfNeeded
-} from "./chunk-RZSTT45F.mjs";
+} from "./chunk-S42YIQNE.mjs";
 import {
   printCommandEnvelope,
   printCompactJson,
@@ -77,12 +80,12 @@ import {
   printJsonError,
   renderCommandEnvelopeText,
   shouldEmitJson
-} from "./chunk-526R2HON.mjs";
+} from "./chunk-NHRWZPWZ.mjs";
 import {
   readSdkSkillsLocalVersion,
   resolveConfig,
   sdkCliStateDirPath
-} from "./chunk-OMM54B3X.mjs";
+} from "./chunk-D6DXOUTO.mjs";
 import {
   DeeplineError
 } from "./chunk-HBL4PM5Q.mjs";
@@ -139,22 +142,49 @@ import {
   existsSync,
   linkSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
+  statSync,
   unlinkSync,
   writeFileSync
 } from "fs";
 import { dirname, join } from "path";
+var PENDING_KEY_TTL_MS = 60 * 60 * 1e3;
+var PENDING_PREFIX = "pending-tool-execution-";
 var ToolCallRecovery = class _ToolCallRecovery {
-  constructor(idempotencyKey, path) {
+  constructor(idempotencyKey, path, resumed = false) {
     this.idempotencyKey = idempotencyKey;
     this.path = path;
+    this.resumed = resumed;
   }
   static open(input) {
     if (!input.recover || input.idempotencyKey) {
       return new _ToolCallRecovery(input.idempotencyKey, null);
     }
     const path = pendingToolExecutionPath(input);
-    return new _ToolCallRecovery(loadOrCreatePendingToolExecution(path), path);
+    discardExpiredPendingExecutions(dirname(path));
+    if (input.fresh && existsSync(path)) {
+      discard(
+        path,
+        `Discarded the saved retry key for ${input.toolId} (--fresh).`
+      );
+    }
+    const { key, resumed } = loadOrCreatePendingToolExecution(path);
+    return new _ToolCallRecovery(key, path, resumed);
+  }
+  /**
+   * Drop the key after the server answered with a failure: the call ended,
+   * so running it again tries again instead of replaying that failure.
+   */
+  discard() {
+    if (!this.path || !this.idempotencyKey) return;
+    try {
+      if (readPendingToolExecution(this.path) === this.idempotencyKey) {
+        unlinkSync(this.path);
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
   }
   async acknowledgeDelivery() {
     await completePendingToolExecution(this.path, this.idempotencyKey);
@@ -165,14 +195,51 @@ function pendingToolExecutionPath(input) {
   const fingerprint = createHash("sha256").update(config.baseUrl).update("\0").update(createHash("sha256").update(config.apiKey).digest("hex")).update("\0").update(input.toolId).update("\0").update(stableStringify(input.params)).update("\0").update(input.responseIntent).digest("hex");
   return join(
     sdkCliStateDirPath(config.baseUrl),
-    `pending-tool-execution-${fingerprint}.json`
+    `${PENDING_PREFIX}${fingerprint}.json`
   );
 }
+function discard(path, note) {
+  try {
+    unlinkSync(path);
+    process.stderr.write(`${note}
+`);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+function discardExpiredPendingExecutions(directory) {
+  if (!existsSync(directory)) return;
+  const now = Date.now();
+  for (const name of readdirSync(directory)) {
+    if (!name.startsWith(PENDING_PREFIX) || !name.endsWith(".json")) continue;
+    const path = join(directory, name);
+    try {
+      const modified = statSync(path).mtimeMs;
+      if (now - modified <= PENDING_KEY_TTL_MS) continue;
+      discard(
+        path,
+        `Discarded a retry key saved ${new Date(modified).toISOString()}, older than ${PENDING_KEY_TTL_MS / 6e4} minutes; the call runs again.`
+      );
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}
 function loadOrCreatePendingToolExecution(path) {
   mkdirSync(dirname(path), { recursive: true });
   if (existsSync(path)) {
-    return readPendingToolExecution(path);
+    try {
+      return { key: readPendingToolExecution(path), resumed: true };
+    } catch (error) {
+      discard(
+        path,
+        `Discarded an unreadable retry key at ${path} (${error instanceof Error ? error.message : String(error)}).`
+      );
+    }
   }
+  return { key: createPendingToolExecution(path), resumed: false };
+}
+function createPendingToolExecution(path) {
   const idempotencyKey = randomUUID();
   const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
   try {
@@ -276,7 +343,7 @@ function toolConnectionStatusMessage(input) {
 var TOOL_EXECUTE_PREFLIGHT_TIMEOUT_MS = 750;
 var TOOL_COMMAND_TEMPLATES = {
   describe: "deepline describe <toolId>",
-  execute: "deepline tools execute <toolId> --input '{...}'"
+  execute: "deepline run <toolId> --input '{...}'"
 };
 function toListedTool(tool) {
   if (isPlayLikeTool(tool)) {
@@ -293,7 +360,7 @@ function toListedTool(tool) {
     description: listedToolDescription(tool),
     id: tool.toolId,
     type: "tool",
-    executeCommand: `deepline tools execute ${tool.toolId}`
+    executeCommand: `deepline run ${tool.toolId}`
   };
 }
 function parseGrepTerms(query, mode) {
@@ -715,7 +782,7 @@ function isMissingToolMetadataError(error) {
 function playAliasToolErrorMessage(toolId, play) {
   const playName = play.reference ?? play.name;
   return `${toolId} is a play, not a tool.
-Use: deepline plays run ${playName} --input '{...}'
+Use: deepline run ${playName} --input '{...}'
 Inspect its schema with: deepline describe ${playName}`;
 }
 function printPlayAliasToolError(toolId, play) {
@@ -723,7 +790,7 @@ function printPlayAliasToolError(toolId, play) {
 }
 function playLikeToolExecuteErrorMessage(toolId, tool) {
   const playReference = tool ? playReferenceForTool(tool) : null;
-  const nextStep = playReference ? `Use: deepline plays run ${playReference} --input '{...}'` : `Find the maintained workflow with: ${playSearchCommandForToolId(toolId)}`;
+  const nextStep = playReference ? `Use: deepline run ${playReference} --input '{...}'` : `Find the maintained workflow with: ${playSearchCommandForToolId(toolId)}`;
   return [
     `${toolId} is a workflow/play entry, not an atomic provider tool.`,
     nextStep,
@@ -746,20 +813,20 @@ function registerToolsCommands(program) {
     "after",
     `
 Concepts:
-  Tools are atomic provider/API operations. Plays are workflows and must be run
-  through the plays namespace.
+  Tools are atomic provider/API operations; plays are workflows. deepline run
+  runs either.
 
 Common commands:
   deepline search "name and company domain -> work email" --type tools
   deepline describe hunter_email_verifier
-  deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
-  deepline billing usage --request-id <job_id>
+  deepline run hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline billing usage --request-id <request-id>
 
 Output:
-  Use deepline describe for tool contracts.
-  Use execute to run a tool.
-  Read pricing before execution; use the returned next.billing command for its
-  exact charge. Workspace balance changes also include other callers' activity.
+  deepline describe shows a tool's contract and price, and deepline run runs
+  it. The receipt's billing command (next.billing with --json) gives a call's
+  exact charge. Workspace balance changes also include other callers'
+  activity.
 `
   );
   tools.command("connect <provider>").description(
@@ -927,7 +994,7 @@ Examples:
   deepline tools describe deeplineagent --model openai/gpt-5.6-luna
   deepline tools describe ai_inference --estimate-payload @payload.json
   deepline tools describe ai_evaluate --estimate-payload @payload.json
-  deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline run hunter_email_verifier --input '{"email":"a@b.com"}'
 `
     ).option("--json", "Emit JSON output").option(
       "--model <model>",
@@ -971,7 +1038,7 @@ Examples:
         process.exitCode = await narrowView();
         return;
       }
-      const { describeAnything } = await import("./describe-TOMIAT37.mjs");
+      const { describeAnything } = await import("./describe-NLZKKT7C.mjs");
       process.exitCode = await describeAnything(
         toolId,
         {
@@ -991,7 +1058,7 @@ Examples:
       { json: false }
     )
   );
-  tools.command("execute <toolId>").alias("call").description("Execute a tool by id.").addHelpText(
+  tools.command("execute <toolId>", { hidden: true }).alias("call").description("Execute a tool by id.").addHelpText(
     "after",
     `
 Notes:
@@ -1441,9 +1508,7 @@ function printCompactToolContract(tool, requestedToolId) {
     );
     if (message) console.log(`Migration: ${message}`);
     if (replacementToolId) {
-      console.log(
-        `Use: deepline tools execute ${replacementToolId} --input '{...}'`
-      );
+      console.log(`Use: deepline run ${replacementToolId} --input '{...}'`);
     }
     console.log("");
     console.log(
@@ -1833,7 +1898,7 @@ function printToolExecutionHints(value) {
     }
     if (status === "compiled") {
       console.log(
-        "- Compatible per-row Play calls can coalesce; separate tools execute requests do not coalesce."
+        "- Compatible per-row Play calls can coalesce; each separate deepline run call makes its own request."
       );
     } else if (surface !== "docs") {
       console.log(
@@ -1946,9 +2011,9 @@ function apifySyncRecoveryNext(rawResponse) {
   const getDatasetItemsTool = stringField(getDatasetItems, "tool");
   const getDatasetItemsPayload = recordField(getDatasetItems, "payload");
   return {
-    getActorRun: `deepline tools execute ${getActorRunTool} --input ${shellQuote(JSON.stringify(getActorRunPayload))}`,
+    getActorRun: `deepline run ${getActorRunTool} --input ${shellQuote(JSON.stringify(getActorRunPayload))}`,
     ...getDatasetItemsTool && Object.keys(getDatasetItemsPayload).length > 0 ? {
-      getDatasetItems: `deepline tools execute ${getDatasetItemsTool} --input ${shellQuote(JSON.stringify(getDatasetItemsPayload))}`
+      getDatasetItems: `deepline run ${getDatasetItemsTool} --input ${shellQuote(JSON.stringify(getDatasetItemsPayload))}`
     } : {}
   };
 }
@@ -2396,6 +2461,166 @@ function printToolExecutionWarnings(toolId, params, metadata) {
     console.error(`Warning: ${requestWarning.message}`);
   }
 }
+function valueAt(value, path) {
+  return path.split(".").reduce((at, key) => isRecord(at) ? at[key] : void 0, value);
+}
+function declaredOutputs(metadata, envelope, data) {
+  const result = metadata.usageGuidance?.toolExecutionResult;
+  const getters = ["extractedValues", "extractedLists"].flatMap(
+    (kind) => {
+      const group = result?.[kind];
+      return Array.isArray(group) ? group : isRecord(group) ? Object.entries(group).map(([name, getter]) => ({
+        name,
+        ...getter
+      })) : [];
+    }
+  );
+  return getters.flatMap((getter) => {
+    const paths = getter.details?.rawToolOutputPaths ?? getter.details?.candidatePaths ?? [];
+    for (const path of paths) {
+      const value = valueAt(envelope, path);
+      if (value === void 0) continue;
+      const inFile = path.replace(/^toolResponse\.raw(V2)?\./, "");
+      return [
+        {
+          name: getter.name,
+          value,
+          path: valueAt(data, inFile) === void 0 ? null : inFile
+        }
+      ];
+    }
+    return [];
+  });
+}
+function writeToolReceipt(input) {
+  const { response, metadata } = input;
+  const envelope = isRecord(response) ? response : {};
+  const jobId = typeof envelope.job_id === "string" ? envelope.job_id : null;
+  const toolResponse = recordField(envelope, "toolResponse");
+  const data = Object.hasOwn(toolResponse, "rawV2") ? toolResponse.rawV2 : Object.hasOwn(toolResponse, "raw") ? toolResponse.raw : Object.hasOwn(envelope, "output") ? envelope.output : Object.hasOwn(envelope, "result") ? envelope.result : response;
+  const status = typeof envelope.status === "string" ? envelope.status : "completed";
+  const charged = recordField(envelope, "billing").credits_charged;
+  writeExecutionOutput(
+    {
+      id: input.key ?? jobId,
+      status,
+      ...["queued", "running", "pending"].includes(status) ? {} : { data },
+      error: envelope.error ?? null,
+      complete: null,
+      declared: declaredOutputs(metadata, envelope, data),
+      credits: typeof charged === "number" ? charged : null,
+      warnings: [
+        ...input.warnings ?? [],
+        ...extractToolExecutionWarningMessages(response)
+      ],
+      next: {
+        ...apifySyncRecoveryNext(response),
+        ...input.key ? { status: `deepline runs get ${input.key}` } : {},
+        ...jobId ? {
+          billing: `deepline billing usage --request-id ${shellQuote(jobId)} --json`
+        } : {}
+      }
+    },
+    input.output
+  );
+  return status === "failed" || envelope.error ? 1 : 0;
+}
+async function executeToolForReceipt(input) {
+  const { toolId, params, output } = input;
+  let key = null;
+  let retryKey = null;
+  let received = false;
+  try {
+    const cliInvocationId = getToolExecuteInvocationId() ?? beginToolExecuteCommand();
+    const client = new DeeplineClient();
+    const metadata = input.metadata ?? await client.getTool(toolId, { cliInvocationId });
+    printToolExecutionWarnings(toolId, params, metadata);
+    const responseIntent = output.csvOut?.length ? "row_artifact" : "raw";
+    const recovery = ToolCallRecovery.open({
+      toolId,
+      params,
+      responseIntent,
+      recover: true,
+      fresh: input.fresh
+    });
+    key = recovery.idempotencyKey ?? null;
+    retryKey = recovery;
+    const response = await client.executeTool(toolId, params, {
+      responseIntent,
+      ...input.timeoutMs !== void 0 ? { timeout: input.timeoutMs } : {},
+      ...metadata.executionMetadata?.retrySafeTransientHttp === true ? { maxRetries: 2, retryApiErrors: true } : {},
+      ...key ? { idempotencyKey: key } : {},
+      searchRef: recentSearchRef(),
+      cliInvocationId,
+      onResponseReceived: recordApiResponse
+    }).catch((error) => {
+      const guidance = toolGuidanceLines(metadata.guidance);
+      if (guidance.length)
+        console.error([`Guidance for ${toolId}:`, ...guidance].join("\n"));
+      throw error;
+    });
+    received = true;
+    const code = writeToolReceipt({
+      key,
+      metadata,
+      response,
+      output,
+      warnings: recovery.resumed ? [
+        "Resumed an interrupted call with its saved retry key; it was not charged again. --fresh calls the provider again."
+      ] : []
+    });
+    await recovery.acknowledgeDelivery();
+    return code;
+  } catch (error) {
+    if (received) throw error;
+    const outcomeKnown = answeredWithFailure(error);
+    if (outcomeKnown) retryKey?.discard();
+    writeExecutionOutput(
+      {
+        id: outcomeKnown ? null : key,
+        status: "failed",
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          ...error instanceof DeeplineError ? { code: error.code } : {}
+        },
+        ...key && !outcomeKnown ? {
+          next: {
+            retry: "Run the same command again: it picks up this call without paying twice."
+          }
+        } : {}
+      },
+      output
+    );
+    return 1;
+  }
+}
+function answeredWithFailure(error) {
+  return error instanceof DeeplineError && typeof error.statusCode === "number" && error.statusCode < 500 && // A request timeout says nothing about whether the call went through.
+  error.statusCode !== 408 && error.code !== "EXECUTION_OUTCOME_UNKNOWN";
+}
+async function getToolExecutionReceipt(key, output) {
+  const client = new DeeplineClient();
+  const execution = await client.executions.getByKey(key);
+  output.label = `${execution.toolId} (tool)`;
+  if (execution.response === void 0) {
+    writeExecutionOutput(
+      {
+        id: key,
+        status: execution.executionRecovery.state,
+        next: { status: `deepline runs get ${key}` }
+      },
+      output
+    );
+    return 1;
+  }
+  const metadata = await client.getTool(execution.toolId);
+  return writeToolReceipt({
+    key,
+    metadata,
+    response: execution.response,
+    output
+  });
+}
 async function executeTool(toolId, options, compatibilityMetadata, deferCompatibility = false, maintenancePolicy = "configured") {
   const output = toolExecuteJsonOption(options.json);
   const wantsJson = (options.outputFormat ?? "auto").trim().toLowerCase() !== "csv";
@@ -2883,6 +3108,10 @@ export {
   printMonitorTypeContract,
   printCompactToolContract,
   extractToolExecutionWarningMessages,
+  parseToolExecuteTimeout,
   seedToolListScript,
-  buildToolExecuteBaseEnvelope
+  buildToolExecuteBaseEnvelope,
+  writeToolReceipt,
+  executeToolForReceipt,
+  getToolExecutionReceipt
 };

package/dist/cli/{chunk-RBTTUYZZ.js → chunk-7VZHXVOQ.js}

@@ -49,7 +49,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.460",
+  version: "0.3.462",
   updateSummary: {
     introducedIn: "0.3.90",
     summary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release."

package/dist/cli/{chunk-YVBWO647.mjs → chunk-AT636LLU.mjs}

@@ -1,10 +1,10 @@
 import {
   getAuthedHttpClient,
   printCommandEnvelope
-} from "./chunk-526R2HON.mjs";
+} from "./chunk-NHRWZPWZ.mjs";
 import {
   agentSessionIdFromEnvironment
-} from "./chunk-OMM54B3X.mjs";
+} from "./chunk-6RNQGWFD.mjs";
 
 // src/cli/commands/sessions.ts
 import {