@sentry/junior-plugin-api 0.261.0 → 0.263.0

package/dist/index.d.ts

@@ -505,6 +505,29 @@ export declare const dispatchOptionsSchema: z.ZodObject<{
     detail: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
   }, z.core.$strict>>;
 }, z.core.$strict>;
+/** A loaded value and how long to cache it. */
+export interface CacheEntry<T> {
+  /** Omit to return the value without caching it, such as for an incomplete response. */
+  ttlMs?: number;
+  /** Must survive JSON serialization. */
+  value: T;
+}
+/**
+ * Short-lived copies of values that are slow or costly to load, such as
+ * provider API reads. Junior can drop an entry at any time. A lost entry only
+ * costs a reload, so never keep data here that Junior must not lose. Use
+ * `PluginState` for that.
+ */
+export interface PluginCache {
+  /**
+   * Return the cached value for `key`, or call `load` and cache its result.
+   * Concurrent callers share one load. A load that throws is not cached.
+   * `refresh` ignores the cached value and replaces it.
+   */
+  getOrLoad<T>(key: string, load: () => Promise<CacheEntry<T>>, options?: {
+    refresh?: boolean;
+  }): Promise<T>;
+}
 /** Runtime platform name without source or destination coordinates. */
 export type Platform = z.output<typeof platformSchema>;
 export type Actor = z.output<typeof actorSchema>;
@@ -586,6 +609,8 @@ export interface PluginEmbedder {
   }>;
 }
 export interface PluginContext {
+  /** Short-lived cache scoped to this plugin. */
+  cache: PluginCache;
   /** Shared Drizzle database connection for plugin runtime code. */
   db: unknown;
   log: PluginLogger;
@@ -1805,8 +1830,23 @@ export interface PluginEnv {
   get(key: string): string | undefined;
   set(key: string, value: string): void;
 }
+/**
+ * Decide what happens to one tool call in `beforeToolExecute`.
+ *
+ * `redirect` and `deny` both stop the tool before it runs. Neither ends the
+ * turn: the agent gets the message as the tool result.
+ */
 export interface PluginDecision {
-  deny(message: string): void;
+  /**
+   * Block the call as a policy refusal. The agent is told not to retry or
+   * reach the same result another way, and to explain the block.
+   */
+  deny(reason: string): void;
+  /**
+   * Block the call because a different path is correct, such as another
+   * tool. The message tells the agent what to do instead.
+   */
+  redirect(message: string): void;
   replaceInput(input: Record<string, unknown>): void;
 }
 /** Thrown when a plugin tool rejects invalid model or user input. */
@@ -2180,6 +2220,13 @@ export interface PluginEventToolContext {
   }): Promise<WatchResult>;
 }
 export interface PluginWorkspaceToolContext {
+  /**
+   * Workspace that the current Sandbox started from. Returns undefined for
+   * the default Sandbox. `name` is missing when the recipe no longer exists.
+   */
+  active(): Promise<{
+    name?: string;
+  } | undefined>;
   /** Find named Workspaces that include one provider repository. */
   findByRepository(input: {
     provider: string;
@@ -2235,6 +2282,20 @@ export declare function enforceEgressPolicy(input: {
   allowed: boolean;
   denialMessage: string;
 }): void;
+/**
+ * Split bash command text into simple commands.
+ *
+ * Plugins use this in `beforeToolExecute` to check `bash` tool input. It is a
+ * small parser, not a full shell. It reads quotes, backslashes, control
+ * operators, comments, redirections, and heredocs. It does not expand
+ * variables, aliases, or globs. It does not look inside `sh -c` or `eval`
+ * strings. Use it for best-effort steering only, not as a security boundary.
+ *
+ * Each result is the argv of one simple command. Leading `NAME=value`
+ * assignments, redirections, and heredoc bodies are removed. Text inside
+ * `$(...)`, backticks, and subshells becomes separate commands.
+ */
+export declare function parseShellCommands(text: string): string[][];
 /** Input for a pure Markdown rewrite before destination delivery formatting. */
 export interface FormatMarkdownHookContext {
   text: string;

package/dist/index.js

@@ -1124,6 +1124,132 @@ var EgressPolicyDenied = class extends Error {
 function enforceEgressPolicy(input) {
 	if (!input.allowed) throw new EgressPolicyDenied(input.denialMessage);
 }
+// src/shell-command.ts
+/**
+* Split bash command text into simple commands.
+*
+* Plugins use this in `beforeToolExecute` to check `bash` tool input. It is a
+* small parser, not a full shell. It reads quotes, backslashes, control
+* operators, comments, redirections, and heredocs. It does not expand
+* variables, aliases, or globs. It does not look inside `sh -c` or `eval`
+* strings. Use it for best-effort steering only, not as a security boundary.
+*
+* Each result is the argv of one simple command. Leading `NAME=value`
+* assignments, redirections, and heredoc bodies are removed. Text inside
+* `$(...)`, backticks, and subshells becomes separate commands.
+*/
+function parseShellCommands(text) {
+	const commands = [];
+	const heredocs = [];
+	let words = [];
+	let word = "";
+	let inWord = false;
+	let skipNextWord = false;
+	const endWord = () => {
+		if (inWord) {
+			if (!skipNextWord) words.push(word);
+			skipNextWord = false;
+		}
+		word = "";
+		inWord = false;
+	};
+	const endCommand = () => {
+		endWord();
+		skipNextWord = false;
+		let start = 0;
+		while (start < words.length && ASSIGNMENT_RE.test(words[start])) start += 1;
+		if (start < words.length) commands.push(words.slice(start));
+		words = [];
+	};
+	for (let index = 0; index < text.length; index += 1) {
+		const char = text[index];
+		if (char === "'") {
+			const end = text.indexOf("'", index + 1);
+			const close = end === -1 ? text.length : end;
+			word += text.slice(index + 1, close);
+			inWord = true;
+			index = close;
+		} else if (char === "\"") {
+			inWord = true;
+			for (index += 1; index < text.length && text[index] !== "\""; index += 1) {
+				if (text[index] === "\\" && DOUBLE_QUOTE_ESCAPES.has(text[index + 1])) index += 1;
+				word += text[index];
+			}
+		} else if (char === "\\") {
+			index += 1;
+			if (index < text.length && text[index] !== "\n") {
+				word += text[index];
+				inWord = true;
+			}
+		} else if (char === "#" && !inWord) {
+			const end = text.indexOf("\n", index);
+			index = (end === -1 ? text.length : end) - 1;
+		} else if (char === "\n") {
+			endCommand();
+			for (const heredoc of heredocs.splice(0)) index = skipHeredocBody(text, index, heredoc);
+		} else if (char === "<" || char === ">") {
+			if (/^\d+$/.test(word)) {
+				word = "";
+				inWord = false;
+			}
+			endWord();
+			if (text.startsWith("<<<", index)) {
+				index += 2;
+				skipNextWord = true;
+			} else if (text.startsWith("<<", index)) {
+				index += 2;
+				const stripTabs = text[index] === "-";
+				if (stripTabs) index += 1;
+				while (text[index] === " " || text[index] === "	") index += 1;
+				let delimiter = "";
+				while (index < text.length && !/[\s;&|()<>]/.test(text[index])) {
+					if (!/['"\\]/.test(text[index])) delimiter += text[index];
+					index += 1;
+				}
+				index -= 1;
+				heredocs.push({
+					delimiter,
+					stripTabs
+				});
+			} else {
+				while (/[<>&|]/.test(text[index + 1] ?? "")) index += 1;
+				skipNextWord = true;
+			}
+		} else if (/[;&|()`]/.test(char)) {
+			if (char === "(" && word.endsWith("$")) {
+				word = word.slice(0, -1);
+				inWord = word.length > 0;
+			}
+			endCommand();
+		} else if (/\s/.test(char)) endWord();
+		else {
+			word += char;
+			inWord = true;
+		}
+	}
+	endCommand();
+	return commands;
+}
+const ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const DOUBLE_QUOTE_ESCAPES = /* @__PURE__ */ new Set([
+	"\"",
+	"\\",
+	"$",
+	"`"
+]);
+/** Return the index of the newline that ends the heredoc delimiter line. */
+function skipHeredocBody(text, newlineIndex, heredoc) {
+	let index = newlineIndex;
+	while (index < text.length) {
+		const start = index + 1;
+		const found = text.indexOf("\n", start);
+		const end = found === -1 ? text.length : found;
+		const line = text.slice(start, end);
+		index = end;
+		if ((heredoc.stripTabs ? line.replace(/^\t+/, "") : line) === heredoc.delimiter) break;
+	}
+	return index;
+}
 // src/registration.ts
 const PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
 const USER_PAGE_ID_RE = /^[a-z][a-z0-9-]*$/;
@@ -1242,4 +1368,4 @@ const pluginUserPageInputSchema = z.object({
 	limit: z.number().int().min(1).max(50),
 	query: pluginUserPageQuerySchema
 }).strict();
-export { EVENT_DATA_MAX_JSON_BYTES, EVENT_DATA_MAX_KEYS, EVENT_GUIDANCE_MAX_LENGTH, EVENT_SUMMARY_MAX_LENGTH, EVENT_TEXT_MAX_LENGTH, EgressAuthRequired, EgressPolicyDenied, PluginToolInputError, REQUIRED_TOOL_ANNOTATION_KEYS, actorSchema, actorUserIdSchema, agentInvocationSourceSchema, codeChangeInputSchema, codeChangeStateSchema, conversationAnnotationInputSchema, conversationEventIconSchema, conversationEventPresentationSchema, conversationSidebarAnnotationSchema, conversationSidebarIconSchema, createEventSource, createLocalSource, createSlackSource, createWebSource, defineConversationEvent, defineJuniorPlugin, definePluginTool, definePromptContext, destinationSchema, destinationVisibilitySchema, dispatchOptionsSchema, enforceEgressPolicy, eventAutomationSourceSchema, eventDataSchema, eventIdentifierSchema, eventInputSchema, eventMatchFieldSchema, eventMatchFieldsSchema, eventMatchSchema, eventMatches, eventPersonSchema, eventSchema, eventSourceSchema, eventTypeSchema, getSourceKey, identitySchema, isPrivateSource, isSlackDestination, localActorSchema, localDestinationSchema, localSourceSchema, locationSchema, missingToolAnnotationKeys, nonBlankStringSchema, normalizeEventIdentifier, objectAnnotationSchema, objectFactFields, objectFactsSchema, objectIconPath, objectIconPaths, objectPresentation, objectTypeSchema, ownedObjectAnnotationSchema, platformSchema, pluginApiRouteRequestContextSchema, pluginAuthorizationSchema, pluginCredentialHeaderTransformSchema, pluginCredentialLeaseSchema, pluginCredentialResultSchema, pluginCredentialSubjectSchema, pluginDispatchSourceSchema, pluginEventTypeSchema, pluginEventsSchema, pluginGrantSchema, pluginProviderAccountSchema, pluginRunContextSchema, pluginRunTranscriptEntrySchema, pluginRunTranscriptProvenanceSchema, pluginStoredTokensSchema, pluginToolContentSchema, pluginToolContinuationSchema, pluginToolOutputSchema, pluginUserPageContentSchema, pluginUserPageCursorSchema, pluginUserPageFilterSchema, pluginUserPageInputSchema, pluginUserPageLinkSchema, pluginUserPageLinksSchema, pluginUserPageQuerySchema, promptContextSchema, promptMessageSchema, replyAttributionSchema, resourceLinkAnnotationSchema, resourceTypeSchema, scheduledAutomationSourceSchema, slackActorSchema, slackDestinationSchema, slackLocationSchema, slackSourceSchema, sourceSchema, sourceVisibilitySchema, stableEventMatchKey, subscribableResourceSchema, systemActorSchema, taskOutcomeSchema, toolApprovalModeSchema, userSchema, watchResultSchema, webActorSchema, webSourceSchema, zodTool };
+export { EVENT_DATA_MAX_JSON_BYTES, EVENT_DATA_MAX_KEYS, EVENT_GUIDANCE_MAX_LENGTH, EVENT_SUMMARY_MAX_LENGTH, EVENT_TEXT_MAX_LENGTH, EgressAuthRequired, EgressPolicyDenied, PluginToolInputError, REQUIRED_TOOL_ANNOTATION_KEYS, actorSchema, actorUserIdSchema, agentInvocationSourceSchema, codeChangeInputSchema, codeChangeStateSchema, conversationAnnotationInputSchema, conversationEventIconSchema, conversationEventPresentationSchema, conversationSidebarAnnotationSchema, conversationSidebarIconSchema, createEventSource, createLocalSource, createSlackSource, createWebSource, defineConversationEvent, defineJuniorPlugin, definePluginTool, definePromptContext, destinationSchema, destinationVisibilitySchema, dispatchOptionsSchema, enforceEgressPolicy, eventAutomationSourceSchema, eventDataSchema, eventIdentifierSchema, eventInputSchema, eventMatchFieldSchema, eventMatchFieldsSchema, eventMatchSchema, eventMatches, eventPersonSchema, eventSchema, eventSourceSchema, eventTypeSchema, getSourceKey, identitySchema, isPrivateSource, isSlackDestination, localActorSchema, localDestinationSchema, localSourceSchema, locationSchema, missingToolAnnotationKeys, nonBlankStringSchema, normalizeEventIdentifier, objectAnnotationSchema, objectFactFields, objectFactsSchema, objectIconPath, objectIconPaths, objectPresentation, objectTypeSchema, ownedObjectAnnotationSchema, parseShellCommands, platformSchema, pluginApiRouteRequestContextSchema, pluginAuthorizationSchema, pluginCredentialHeaderTransformSchema, pluginCredentialLeaseSchema, pluginCredentialResultSchema, pluginCredentialSubjectSchema, pluginDispatchSourceSchema, pluginEventTypeSchema, pluginEventsSchema, pluginGrantSchema, pluginProviderAccountSchema, pluginRunContextSchema, pluginRunTranscriptEntrySchema, pluginRunTranscriptProvenanceSchema, pluginStoredTokensSchema, pluginToolContentSchema, pluginToolContinuationSchema, pluginToolOutputSchema, pluginUserPageContentSchema, pluginUserPageCursorSchema, pluginUserPageFilterSchema, pluginUserPageInputSchema, pluginUserPageLinkSchema, pluginUserPageLinksSchema, pluginUserPageQuerySchema, promptContextSchema, promptMessageSchema, replyAttributionSchema, resourceLinkAnnotationSchema, resourceTypeSchema, scheduledAutomationSourceSchema, slackActorSchema, slackDestinationSchema, slackLocationSchema, slackSourceSchema, sourceSchema, sourceVisibilitySchema, stableEventMatchKey, subscribableResourceSchema, systemActorSchema, taskOutcomeSchema, toolApprovalModeSchema, userSchema, watchResultSchema, webActorSchema, webSourceSchema, zodTool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.261.0",
+  "version": "0.263.0",
   "private": false,
   "publishConfig": {
     "access": "public"