@ganju/utils 0.0.10 → 0.0.12

package/src/index.ts

@@ -117,7 +117,11 @@ import type { OAuthProviderConfig } from './oauthProviders';
 import { resolveAttachment } from './attachment';
 import { isExposedResource } from './exposedResource';
 import type { ExposableResource } from './exposedResource';
-import { isSyncableResource, resourceSyncProvider } from './syncableResource';
+import {
+  isSyncableResource,
+  isResourceSyncInProgress,
+  resourceSyncProvider
+} from './syncableResource';
 import type {
   SyncableResource,
   ResourceSyncProvider
@@ -169,6 +173,7 @@ import type {
   CatalogGroup,
   CatalogTool,
   CatalogToolDescriptor,
+  ToolAnnotations,
   ToolGroupKey,
   ToolKey
 } from './toolCatalog';
@@ -220,6 +225,35 @@ import type {
   ChannelBufferEnvelope,
   ChannelBufferFlush
 } from './channelDebounce';
+import {
+  isConfirmationReply,
+  confirmationButtonLabels,
+  confirmationButtonId,
+  parseConfirmationButton,
+  languageFromPhoneNumber,
+  formatConfirmationSummary,
+  annotationsForEffect,
+  TOOL_EFFECTS,
+  isSensitiveTool,
+  stableJson
+} from './toolConfirmation';
+import type {
+  PendingToolConfirmation,
+  PendingToolConfirmations,
+  ToolEffect
+} from './toolConfirmation';
+import {
+  lintTools,
+  TOOL_LINT_RULES,
+  TOOL_LINT_MAX_TOOLS,
+  TOOL_LINT_MIN_DESCRIPTION_LENGTH
+} from './toolLint';
+import type {
+  LintableTool,
+  ToolLintFinding,
+  ToolLintOptions,
+  ToolLintRule
+} from './toolLint';
 import {
   isResourceSourceEnabled,
   isDownloadableSource,
@@ -301,6 +335,7 @@ export const utils = {
   resolveAttachment,
   isExposedResource,
   isSyncableResource,
+  isResourceSyncInProgress,
   resourceSyncProvider,
   describeVendorError,
   withDeadline,
@@ -358,6 +393,20 @@ export const utils = {
   channelBufferKey,
   batchCommand,
   joinBufferedMessages,
+  isConfirmationReply,
+  confirmationButtonLabels,
+  confirmationButtonId,
+  parseConfirmationButton,
+  languageFromPhoneNumber,
+  formatConfirmationSummary,
+  annotationsForEffect,
+  TOOL_EFFECTS,
+  isSensitiveTool,
+  stableJson,
+  lintTools,
+  TOOL_LINT_RULES,
+  TOOL_LINT_MAX_TOOLS,
+  TOOL_LINT_MIN_DESCRIPTION_LENGTH,
   isResourceSourceEnabled,
   isDownloadableSource,
   safeHostname,
@@ -386,6 +435,14 @@ export type {
   CatalogGroup,
   CatalogTool,
   CatalogToolDescriptor,
+  ToolAnnotations,
+  PendingToolConfirmation,
+  PendingToolConfirmations,
+  ToolEffect,
+  LintableTool,
+  ToolLintFinding,
+  ToolLintOptions,
+  ToolLintRule,
   ToolGroupKey,
   ToolKey,
   CalendarConfigField,

package/src/schema.ts

@@ -5,6 +5,7 @@ import { isAllowedLlmBaseUrl, requiresLlmBaseUrl } from './llmBaseUrl';
 import { isReservedSlug, isValidSlugFormat } from './slug';
 import { isReservedToolName } from './reservedToolName';
 import { slugifyTitle } from './slugifyTitle';
+import { TOOL_EFFECTS } from './toolConfirmation';
 
 // A prompt title becomes a slash command; it must not collide with a command
 // the channel runner handles itself (e.g. `/link`).
@@ -43,11 +44,20 @@ const ORGANIZATION_CREATE_VIEW = z.object({
   projectDescription: z.string().max(500)
 });
 
-const ORGANIZATION_UPDATE = z.object({
-  id: z.uuid(),
-  userId: z.uuid(),
-  name: z.string().min(3).max(100)
-});
+// Each setting is saved on its own — the name from its form, the switches the
+// moment they're flipped — so every field is optional, but not all at once.
+const ORGANIZATION_UPDATE = z
+  .object({
+    id: z.uuid(),
+    userId: z.uuid(),
+    name: z.string().min(3).max(100).optional(),
+    requireToolConfirmation: z.boolean().optional()
+  })
+  .refine(
+    value =>
+      value.name !== undefined || value.requireToolConfirmation !== undefined,
+    { message: 'Nothing to update' }
+  );
 
 const ORGANIZATION_GET = z.object({
   id: z.uuid(),
@@ -851,6 +861,12 @@ const HTTP_ENDPOINT_CONFIG = z
         contentType: constants.HTTP_ENDPOINT_RESPONSE_CONTENT_TYPE_AUTO,
         maxBytes: constants.HTTP_ENDPOINT_DEFAULT_MAX_BYTES
       }),
+    // What the endpoint does, as its owner says (`read`, `write` or
+    // `sensitive`). Absent means the method decides: GET and HEAD read,
+    // anything else is sensitive — right for most, but a POST that only
+    // searches needs its owner to say so, or a confirming channel asks
+    // before every search.
+    effect: z.enum(TOOL_EFFECTS).optional(),
     // Auth — credentials referenced by id, never inlined.
     auth: HTTP_ENDPOINT_AUTH.default({
       kind: constants.HTTP_ENDPOINT_AUTH_KIND_NONE
@@ -1056,6 +1072,19 @@ const CUSTOM_CODE_CONFIG_WRITE = CUSTOM_CODE_CONFIG.superRefine((cfg, ctx) => {
 // that version registering, and the owner would see tools quietly disappear with
 // only a log line to explain it. Reservation belongs to the manifest below,
 // which is the write path.
+// MCP tool annotations as a tool's author declares them — every hint optional,
+// with the spec's own defaults for what is left out. The channel runner reads
+// them to decide what to confirm, so a tool that doesn't say it is read-only
+// is treated as one that may change things.
+const TOOL_ANNOTATIONS = z
+  .object({
+    readOnlyHint: z.boolean().optional(),
+    destructiveHint: z.boolean().optional(),
+    idempotentHint: z.boolean().optional(),
+    openWorldHint: z.boolean().optional()
+  })
+  .strict();
+
 const CUSTOM_CODE_TOOL = z.object({
   name: z
     .string()
@@ -1068,7 +1097,8 @@ const CUSTOM_CODE_TOOL = z.object({
   title: z.string().min(1).max(200).optional(),
   description: z.string().max(2000).optional(),
   inputSchema: SCHEMA_DEFINITION.default({ type: 'object', properties: {} }),
-  outputSchema: SCHEMA_DEFINITION.optional()
+  outputSchema: SCHEMA_DEFINITION.optional(),
+  annotations: TOOL_ANNOTATIONS.optional()
 });
 
 // The manifest a `ganju deploy` (or the dashboard) uploads alongside a bundle.
@@ -1648,6 +1678,7 @@ export const Schema = {
   CUSTOM_CODE_CONFIG,
   CUSTOM_CODE_CONFIG_WRITE,
   CUSTOM_CODE_TOOL,
+  TOOL_ANNOTATIONS,
   CUSTOM_CODE_MANIFEST,
   ARTIFACT_CUSTOM_CODE_CREATE_VERSION,
   ARTIFACT_CUSTOM_CODE_UPLOAD_BUNDLE,
@@ -1707,6 +1738,10 @@ export interface McpProxyDiscoveredTool {
   title?: string;
   description?: string;
   inputSchema: unknown;
+  // The remote's own annotations, passed through at registration. Absent on
+  // discoveries made before they were recorded — the tool then counts as one
+  // that may change things until the server is discovered again.
+  annotations?: z.infer<typeof TOOL_ANNOTATIONS>;
 }
 
 // One remote resource discovered from a proxied MCP server. Identified by uri;

package/src/syncableResource.ts

@@ -46,3 +46,23 @@ export const resourceSyncProvider = (
 
 export const isSyncableResource = (resource: SyncableResource): boolean =>
   resourceSyncProvider(resource) !== null;
+
+// Whether a sync root is still genuinely syncing: PENDING, and started within
+// RESOURCE_SYNC_STALE_MS. Past that, a PENDING root is stuck — a job was lost
+// or gave up — and may be synced again, which re-queues whatever it left
+// unfinished. A root that never synced counts from its creation, so a first
+// import that stalled recovers too.
+export const isResourceSyncInProgress = (
+  resource: {
+    status: string;
+    syncStartedAt?: Date | string | null;
+    createdAt: Date | string;
+  },
+  now: number = Date.now()
+): boolean => {
+  if (resource.status !== constants.STATUS_PENDING) return false;
+  const startedAt = new Date(
+    resource.syncStartedAt ?? resource.createdAt
+  ).getTime();
+  return now - startedAt < constants.RESOURCE_SYNC_STALE_MS;
+};