@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/tools/fetch/schema.d.ts

@@ -0,0 +1,252 @@
+/**
+ * JSON Schema definition for the `fetch` tool.
+ *
+ * The fetch tool performs HTTP requests in batch, with per-URL extract modes,
+ * timeout support, and token-efficient verbosity output.
+ */
+export declare const FETCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly urls: {
+            readonly type: "array";
+            readonly description: "URLs to fetch. Processed as a batch in one call.";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly url: {
+                        readonly type: "string";
+                        readonly description: "The URL to fetch.";
+                    };
+                    readonly method: {
+                        readonly type: "string";
+                        readonly enum: readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+                        readonly description: "HTTP method. Defaults to GET.";
+                    };
+                    readonly params: {
+                        readonly type: "object";
+                        readonly description: "Query parameters to append to the URL as a query string.";
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly headers: {
+                        readonly type: "object";
+                        readonly description: "HTTP headers to include in the request.";
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly body: {
+                        readonly type: "string";
+                        readonly description: "Request body string.";
+                    };
+                    readonly body_base64: {
+                        readonly type: "string";
+                        readonly description: "Base64-encoded request body. Decoded before sending. Takes precedence over body.";
+                    };
+                    readonly body_type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["json", "form", "raw", "multipart"];
+                        readonly description: string;
+                    };
+                    readonly body_data: {
+                        readonly type: "object";
+                        readonly description: string;
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly extract: {
+                        readonly type: "string";
+                        readonly enum: readonly ["raw", "text", "json", "markdown", "readable", "code_blocks", "links", "metadata", "structured", "tables", "pdf", "summary"];
+                        readonly description: string;
+                    };
+                    readonly selectors: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "CSS selectors for structured extraction mode. Each matched element text is returned as an array item.";
+                    };
+                    readonly timeout_ms: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly description: "Per-URL timeout in milliseconds. Default 30000.";
+                    };
+                    readonly max_content_length: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly description: "Maximum response body size in bytes. Responses exceeding this are truncated. Overrides global max_content_length.";
+                    };
+                    readonly retry_on_auth: {
+                        readonly type: "boolean";
+                        readonly description: "When a service is specified and a 401 is returned, attempt to refresh auth and retry once. Defaults to true when service is specified.";
+                    };
+                    readonly service: {
+                        readonly type: "string";
+                        readonly description: "Named service for automatic credential lookup from the service registry. Services are configured in .goodvibes/sdk/services.json. Use the registry tool or check .goodvibes/sdk/services.json to discover available service names.";
+                    };
+                    readonly auth: {
+                        readonly type: "object";
+                        readonly description: "Inline auth configuration. Applied directly without registry lookup.";
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["bearer", "basic", "api-key"];
+                                readonly description: "Auth type.";
+                            };
+                            readonly token: {
+                                readonly type: "string";
+                                readonly description: "Bearer token (for type bearer).";
+                            };
+                            readonly username: {
+                                readonly type: "string";
+                                readonly description: "Username (for type basic).";
+                            };
+                            readonly password: {
+                                readonly type: "string";
+                                readonly description: "Password (for type basic).";
+                            };
+                            readonly header: {
+                                readonly type: "string";
+                                readonly description: "Header name (for type api-key). Defaults to X-API-Key.";
+                            };
+                            readonly key: {
+                                readonly type: "string";
+                                readonly description: "API key value (for type api-key).";
+                            };
+                        };
+                        readonly required: readonly ["type"];
+                    };
+                };
+                readonly required: readonly ["url"];
+            };
+            readonly minItems: 1;
+        };
+        readonly extract: {
+            readonly type: "string";
+            readonly enum: readonly ["raw", "text", "json", "markdown", "readable", "code_blocks", "links", "metadata", "structured", "tables", "pdf", "summary"];
+            readonly description: "Global extraction mode applied to all URLs unless overridden per-URL. Defaults to raw.";
+        };
+        readonly parallel: {
+            readonly type: "boolean";
+            readonly description: "Fetch URLs in parallel using Promise.all. Default true.";
+        };
+        readonly verbosity: {
+            readonly type: "string";
+            readonly enum: readonly ["count_only", "minimal", "standard", "verbose"];
+            readonly description: string;
+        };
+        readonly cache_ttl_seconds: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Cache GET responses by URL+params for this many seconds. 0 disables caching (default).";
+        };
+        readonly rate_limit_ms: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Minimum delay in milliseconds between sequential requests. 0 disables rate limiting (default). Has no effect in parallel mode.";
+        };
+        readonly max_content_length: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "Global maximum response body size in bytes. Responses exceeding this are truncated. Can be overridden per-URL.";
+        };
+        readonly sanitize_mode: {
+            readonly type: "string";
+            readonly enum: readonly ["none", "safe-text", "strict"];
+            readonly description: string;
+        };
+        readonly trusted_hosts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Hostnames or glob patterns explicitly trusted. Trusted hosts may use sanitize_mode: none.";
+        };
+        readonly blocked_hosts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Hostnames or glob patterns explicitly blocked. Denied pre-request regardless of other config.";
+        };
+    };
+    readonly required: readonly ["urls"];
+};
+/** Extraction mode for a single URL or globally. */
+export type FetchExtractMode = 'raw' | 'text' | 'json' | 'markdown' | 'readable' | 'code_blocks' | 'links' | 'metadata' | 'structured' | 'tables' | 'pdf' | 'summary';
+/** Output verbosity format. */
+export type FetchVerbosity = 'count_only' | 'minimal' | 'standard' | 'verbose';
+/** Auth config for a single URL. */
+export interface FetchAuthInput {
+    type: 'bearer' | 'basic' | 'api-key';
+    /** Bearer token (used with type 'bearer'). */
+    token?: string;
+    /** Username for basic auth (used with type 'basic'). */
+    username?: string;
+    /** Password for basic auth (used with type 'basic'). */
+    password?: string;
+    /** Header name for API key auth (used with type 'api-key'). Defaults to X-API-Key. */
+    header?: string;
+    /** API key value (used with type 'api-key'). */
+    key?: string;
+}
+/** Input shape for a single URL entry. */
+export interface FetchUrlInput {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+    /** Query parameters appended as a query string to the URL. */
+    params?: Record<string, string>;
+    headers?: Record<string, string>;
+    body?: string;
+    /** Base64-encoded request body. Decoded before sending. Takes precedence over body. */
+    body_base64?: string;
+    body_type?: 'json' | 'form' | 'raw' | 'multipart';
+    /** Key-value pairs used when body_type is 'form' or 'multipart'. */
+    body_data?: Record<string, string>;
+    extract?: FetchExtractMode;
+    /** CSS selectors for structured extraction mode. */
+    selectors?: string[];
+    timeout_ms?: number;
+    /** Maximum response body size in bytes. Overrides global max_content_length. */
+    max_content_length?: number;
+    /** When a service is specified and a 401 is returned, refresh auth and retry once. */
+    retry_on_auth?: boolean;
+    /** Named service for automatic credential lookup from the service registry. */
+    service?: string;
+    /** Inline auth configuration. Applied directly without registry lookup. */
+    auth?: FetchAuthInput;
+}
+/**
+ * Sanitization mode for response content.
+ *
+ * Re-exported from sanitizer.ts to avoid duplication. `FetchSanitizeMode`
+ * is an alias for `SanitizeMode`.
+ */
+import type { SanitizeMode } from './sanitizer.js';
+/** Sanitization mode alias — re-exported from sanitizer.ts to avoid duplication. */
+export type FetchSanitizeMode = SanitizeMode;
+/** Full input shape for the fetch tool. */
+export interface FetchInput {
+    urls: FetchUrlInput[];
+    extract?: FetchExtractMode;
+    parallel?: boolean;
+    verbosity?: FetchVerbosity;
+    /** Cache GET responses by URL+params for this many seconds. 0 = disabled (default). */
+    cache_ttl_seconds?: number;
+    /** Minimum delay in ms between sequential requests. 0 = disabled (default). */
+    rate_limit_ms?: number;
+    /** Global maximum response body size in bytes. */
+    max_content_length?: number;
+    /**
+     * Response sanitization mode applied to all URL responses.
+     * Defaults to `'safe-text'` when omitted (rollback-safe default for fetch sanitization).
+     */
+    sanitize_mode?: FetchSanitizeMode;
+    /** Hostnames or glob patterns explicitly trusted. Trusted hosts may use sanitize_mode: none. */
+    trusted_hosts?: string[];
+    /** Hostnames or glob patterns explicitly blocked. Denied pre-request regardless of other config. */
+    blocked_hosts?: string[];
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/_internal/platform/tools/fetch/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/fetch/schema.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/tools/fetch/schema.js

@@ -0,0 +1,167 @@
+/**
+ * JSON Schema definition for the `fetch` tool.
+ *
+ * The fetch tool performs HTTP requests in batch, with per-URL extract modes,
+ * timeout support, and token-efficient verbosity output.
+ */
+export const FETCH_TOOL_SCHEMA = {
+    type: 'object',
+    properties: {
+        urls: {
+            type: 'array',
+            description: 'URLs to fetch. Processed as a batch in one call.',
+            items: {
+                type: 'object',
+                properties: {
+                    url: {
+                        type: 'string',
+                        description: 'The URL to fetch.',
+                    },
+                    method: {
+                        type: 'string',
+                        enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'],
+                        description: 'HTTP method. Defaults to GET.',
+                    },
+                    params: {
+                        type: 'object',
+                        description: 'Query parameters to append to the URL as a query string.',
+                        additionalProperties: { type: 'string' },
+                    },
+                    headers: {
+                        type: 'object',
+                        description: 'HTTP headers to include in the request.',
+                        additionalProperties: { type: 'string' },
+                    },
+                    body: {
+                        type: 'string',
+                        description: 'Request body string.',
+                    },
+                    body_base64: {
+                        type: 'string',
+                        description: 'Base64-encoded request body. Decoded before sending. Takes precedence over body.',
+                    },
+                    body_type: {
+                        type: 'string',
+                        enum: ['json', 'form', 'raw', 'multipart'],
+                        description: 'How to encode the body. json: sets Content-Type application/json;'
+                            + ' form: URL-encodes body_data or sends body as application/x-www-form-urlencoded;'
+                            + ' multipart: builds a FormData body from body_data (object of key-value pairs);'
+                            + ' raw: sends as-is.',
+                    },
+                    body_data: {
+                        type: 'object',
+                        description: 'Key-value pairs for structured request bodies.'
+                            + ' For form, entries are URL-encoded into the request body.'
+                            + ' For multipart, each entry becomes a FormData field.',
+                        additionalProperties: { type: 'string' },
+                    },
+                    extract: {
+                        type: 'string',
+                        enum: ['raw', 'text', 'json', 'markdown', 'readable', 'code_blocks', 'links', 'metadata', 'structured', 'tables', 'pdf', 'summary'],
+                        description: 'Extraction mode for this URL. Overrides the global extract.'
+                            + ' raw: raw response body; text: plain text, strips HTML tags;'
+                            + ' json: parse and format JSON; markdown: convert HTML to markdown;'
+                            + ' readable: extract main content, strip nav/sidebar/footer;'
+                            + ' code_blocks: extract <pre>/<code> blocks;'
+                            + ' links: extract all URLs; metadata: extract title/og-tags;'
+                            + ' structured: extract text of elements matching CSS selectors (requires selectors field);'
+                            + ' tables: parse <table> elements into JSON arrays;'
+                            + ' pdf: extract text from PDF responses;'
+                            + ' summary: extractive summary (first paragraph + headings).',
+                    },
+                    selectors: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'CSS selectors for structured extraction mode. Each matched element text is returned as an array item.',
+                    },
+                    timeout_ms: {
+                        type: 'integer',
+                        minimum: 1,
+                        description: 'Per-URL timeout in milliseconds. Default 30000.',
+                    },
+                    max_content_length: {
+                        type: 'integer',
+                        minimum: 1,
+                        description: 'Maximum response body size in bytes. Responses exceeding this are truncated. Overrides global max_content_length.',
+                    },
+                    retry_on_auth: {
+                        type: 'boolean',
+                        description: 'When a service is specified and a 401 is returned, attempt to refresh auth and retry once. Defaults to true when service is specified.',
+                    },
+                    service: {
+                        type: 'string',
+                        description: 'Named service for automatic credential lookup from the service registry. Services are configured in .goodvibes/sdk/services.json. Use the registry tool or check .goodvibes/sdk/services.json to discover available service names.',
+                    },
+                    auth: {
+                        type: 'object',
+                        description: 'Inline auth configuration. Applied directly without registry lookup.',
+                        properties: {
+                            type: {
+                                type: 'string',
+                                enum: ['bearer', 'basic', 'api-key'],
+                                description: 'Auth type.',
+                            },
+                            token: { type: 'string', description: 'Bearer token (for type bearer).' },
+                            username: { type: 'string', description: 'Username (for type basic).' },
+                            password: { type: 'string', description: 'Password (for type basic).' },
+                            header: { type: 'string', description: 'Header name (for type api-key). Defaults to X-API-Key.' },
+                            key: { type: 'string', description: 'API key value (for type api-key).' },
+                        },
+                        required: ['type'],
+                    },
+                },
+                required: ['url'],
+            },
+            minItems: 1,
+        },
+        extract: {
+            type: 'string',
+            enum: ['raw', 'text', 'json', 'markdown', 'readable', 'code_blocks', 'links', 'metadata', 'structured', 'tables', 'pdf', 'summary'],
+            description: 'Global extraction mode applied to all URLs unless overridden per-URL. Defaults to raw.',
+        },
+        parallel: {
+            type: 'boolean',
+            description: 'Fetch URLs in parallel using Promise.all. Default true.',
+        },
+        verbosity: {
+            type: 'string',
+            enum: ['count_only', 'minimal', 'standard', 'verbose'],
+            description: 'count_only: totals only; minimal: URL + status + byte size;'
+                + ' standard: URL + status + content (default); verbose: all metadata.',
+        },
+        cache_ttl_seconds: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Cache GET responses by URL+params for this many seconds. 0 disables caching (default).',
+        },
+        rate_limit_ms: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Minimum delay in milliseconds between sequential requests. 0 disables rate limiting (default). Has no effect in parallel mode.',
+        },
+        max_content_length: {
+            type: 'integer',
+            minimum: 1,
+            description: 'Global maximum response body size in bytes. Responses exceeding this are truncated. Can be overridden per-URL.',
+        },
+        sanitize_mode: {
+            type: 'string',
+            enum: ['none', 'safe-text', 'strict'],
+            description: 'Response sanitization mode applied to all URL responses.'
+                + ' none: content returned verbatim (trusted hosts only);'
+                + ' safe-text: strips script/style blocks and control characters (default);'
+                + ' strict: strips all HTML and non-printable characters (untrusted hosts).',
+        },
+        trusted_hosts: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Hostnames or glob patterns explicitly trusted. Trusted hosts may use sanitize_mode: none.',
+        },
+        blocked_hosts: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Hostnames or glob patterns explicitly blocked. Denied pre-request regardless of other config.',
+        },
+    },
+    required: ['urls'],
+};

package/dist/_internal/platform/tools/fetch/trust-tiers.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Host trust tier classification.
+ *
+ * Classifies outbound HTTP request targets into one of three tiers before
+ * the request is sent. Blocked hosts are denied pre-request with an
+ * `SSRF_DENY` telemetry event. Unknown hosts receive `safe-text`
+ * sanitization. Trusted hosts may opt into `none` sanitization via config.
+ *
+ * Trust tiers:
+ *   - `trusted`  — Host is explicitly allowlisted. Sanitization may be relaxed.
+ *   - `unknown`  — Host is not in any list; apply `safe-text` sanitization.
+ *   - `blocked`  — Host matches an internal address, metadata endpoint, or
+ *                  explicit blocklist entry. Request is denied pre-flight.
+ *
+ * SSRF protections detect:
+ *   - Private IPv4 ranges (RFC 1918)
+ *   - IPv6 loopback and link-local
+ *   - Cloud metadata endpoints (169.254.x.x, metadata.google.internal, etc.)
+ *   - Localhost variants
+ *   - DNS rebinding patterns (encoded or obfuscated IP addresses)
+ */
+/**
+ * Trust classification for an outbound request host.
+ *
+ * - `trusted`  — Explicitly allowlisted; sanitization may be relaxed.
+ * - `unknown`  — Not in any list; standard `safe-text` sanitization applied.
+ * - `blocked`  — Internal/sensitive host; request denied pre-request.
+ */
+export type HostTrustTier = 'trusted' | 'unknown' | 'blocked';
+/**
+ * Result of classifying a host's trust tier.
+ */
+export interface TrustTierResult {
+    /** The classified trust tier. */
+    tier: HostTrustTier;
+    /** Human-readable reason for the classification. */
+    reason: string;
+    /** True when the host matched an SSRF pattern specifically. */
+    isSsrf: boolean;
+}
+/**
+ * Configuration for host trust tier classification.
+ */
+export interface TrustTierConfig {
+    /**
+     * Hostnames or glob patterns that are explicitly trusted.
+     * Trusted hosts may opt out of sanitization via fetch config.
+     * Example: `['api.anthropic.com', '*.internal.example.com']`
+     */
+    trustedHosts?: string[];
+    /**
+     * Hostnames or glob patterns that are explicitly blocked.
+     * Blocked hosts are denied pre-request regardless of other config.
+     */
+    blockedHosts?: string[];
+}
+/**
+ * Telemetry event names emitted by the trust tier classifier.
+ * These are the canonical runtime contract strings for host trust classification.
+ */
+export declare const TRUST_TIER_EVENTS: {
+    /** Emitted when a host trust tier has been classified (all tiers). */
+    readonly HOST_TRUST_TIER: "HOST_TRUST_TIER";
+    /** Emitted when a request is denied due to SSRF detection. */
+    readonly SSRF_DENY: "SSRF_DENY";
+};
+/**
+ * Classify the trust tier of an outbound request host.
+ *
+ * Classification order (first match wins):
+ *   1. Explicit blocklist → `blocked`
+ *   2. SSRF patterns (private IPs, metadata endpoints, localhost) → `blocked`
+ *   3. Encoded IP bypass attempts → `blocked`
+ *   4. Explicit trustlist → `trusted`
+ *   5. Default → `unknown`
+ *
+ * @param host   - Hostname or IP to classify (without port).
+ * @param config - Trust tier configuration with optional allow/deny lists.
+ * @returns      `TrustTierResult` with tier, reason, and SSRF flag.
+ */
+export declare function classifyHostTrustTier(host: string, config?: TrustTierConfig): TrustTierResult;
+/**
+ * Emit SSRF deny telemetry to the logger as a structured event.
+ *
+ * Emits a log entry with event name `SSRF_DENY` that can be consumed by
+ * the telemetry pipeline. This fulfils the runtime contract for the
+ * `SSRF_DENY` telemetry event in fetch sanitization.
+ *
+ * @param host     - The host that was denied.
+ * @param url      - The full URL that was attempted.
+ * @param reason   - Human-readable reason for the denial.
+ */
+export declare function emitSsrfDeny(host: string, url: string, reason: string): void;
+/**
+ * Emit host trust tier telemetry to the logger as a structured event.
+ *
+ * Emits a log entry with event name `HOST_TRUST_TIER` that can be consumed
+ * by the telemetry pipeline. This fulfils the runtime contract for the
+ * `HOST_TRUST_TIER` telemetry event in fetch sanitization.
+ *
+ * @param host   - The classified host.
+ * @param url    - The full URL being fetched.
+ * @param result - The trust tier classification result.
+ */
+export declare function emitHostTrustTier(host: string, url: string, result: TrustTierResult): void;
+/**
+ * Extract the hostname from a URL string for trust tier classification.
+ *
+ * Returns `null` if the URL cannot be parsed.
+ *
+ * @param url - Full URL string (e.g. `https://example.com/path`).
+ * @returns   Hostname string (without port), or `null` on parse failure.
+ */
+export declare function extractHostname(url: string): string | null;
+//# sourceMappingURL=trust-tiers.d.ts.map

package/dist/_internal/platform/tools/fetch/trust-tiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-tiers.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/fetch/trust-tiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAsID;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B,sEAAsE;;IAEtE,8DAA8D;;CAEtD,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,eAAoB,GAC3B,eAAe,CA8EjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAQ5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,eAAe,GACtB,IAAI,CAUN;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO1D"}