@futdevpro/nts-dynamo 1.15.463 → 1.15.465

package/build/_modules/ai/_services/ai-agent.control-service.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyNTS_AI_Agent_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const ai_1 = require("@futdevpro/fsm-dynamo/ai");
+const ai_agent_context_util_1 = require("../_collections/ai-agent-context.util");
+/**
+ * BFR-MYASSISTANT-026 — a plain, general agentic loop: the project gives the tools and the context providers, the
+ * model (any `DyNTS_AI_LLM_ServiceBase` provider) runs the tool loop.
+ *
+ * - **tools:** `addTool({ name, description, parameters, handler })` — the definition and the handler in one object;
+ *   a tool's error becomes an `ERROR …` result for the model, a long result is cut (`maxToolResultLength`);
+ * - **context bound to the user message, NOT to the history:** `prepare` runs the context providers (e.g. RAG) for a
+ *   message and gives a draft; the user adjusts it (switches items off, edits, reorders, adds); `run` sends the
+ *   message with exactly that context. The history sent later holds only the messages and the answers — the context
+ *   stays in the turn (shown / audited), it is not resent;
+ * - the context is sent as DATA between markers (`DyNTS_AI_AgentContext_Util`), within `maxContextLength`, and the
+ *   result reports which item was sent, cut, dropped or switched off;
+ * - stateless between requests: the project stores the turns; one instance serves any number of requests.
+ *
+ * @example
+ * ```ts
+ * const agent = new DyNTS_AI_Agent_ControlService({ llm: openAiService, systemPrompt: 'You are the order assistant.' })
+ *   .addTool({ name: 'find_order', description: 'Finds an order by id.', parameters: orderIdSchema,
+ *     handler: (args) => this.orders.describe(`${args.id}`) })
+ *   .addContextProvider({ name: 'docs', provide: ({ message }) => this.rag.search(message) });
+ *
+ * const draft = await agent.prepare({ message: text, history: turns });   // ⇒ to the client, adjusted there
+ * const result = await agent.run({ draft: adjustedDraft, history: turns, issuer: accountId });
+ * turns.push(result.turn);
+ * ```
+ */
+class DyNTS_AI_Agent_ControlService {
+    settings;
+    /** The longest user message accepted (characters). */
+    static maxMessageLength = 20000;
+    /** The most context items of one message. */
+    static maxContextItems = 50;
+    /** A tool name the providers accept (OpenAI / Anthropic / Gemini). */
+    static toolNamePattern = /^[a-zA-Z0-9_-]{1,64}$/;
+    /** The defaults of the optional settings. */
+    static defaults = { maxIterations: 8, historyLimit: 20, maxContextLength: 12000, maxToolResultLength: 20000 };
+    /** The tools, by name. */
+    tools = new Map();
+    /** The context providers, in their order. */
+    contextProviders = [];
+    /** An agent with its model and limits; the tools and the context providers are added after. */
+    constructor(settings) {
+        this.settings = settings;
+    }
+    /** The registered tools' names. */
+    getToolNames() {
+        return [...this.tools.keys()];
+    }
+    /** The registered context providers' names. */
+    getContextProviderNames() {
+        return this.contextProviders.map((provider) => provider.name);
+    }
+    /** Adds a tool (a unique, provider-safe name). */
+    addTool(tool) {
+        if (!DyNTS_AI_Agent_ControlService.toolNamePattern.test(tool?.name ?? '') || typeof tool.handler !== 'function') {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'DyNTS-AIAG-TL1',
+                message: `Invalid agent tool '${tool?.name}': the name must match `
+                    + `${DyNTS_AI_Agent_ControlService.toolNamePattern} and a handler is required.`,
+            });
+        }
+        if (this.tools.has(tool.name)) {
+            throw new fsm_dynamo_1.DyFM_Error({ errorCode: 'DyNTS-AIAG-TL2', message: `The agent tool '${tool.name}' is already added.` });
+        }
+        this.tools.set(tool.name, tool);
+        return this;
+    }
+    /** Adds a context provider (a unique name). */
+    addContextProvider(provider) {
+        const name = provider?.name?.trim() ?? '';
+        if (!name || typeof provider.provide !== 'function' || name === ai_agent_context_util_1.DyNTS_AI_AgentContext_Util.userProviderName) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'DyNTS-AIAG-CP1',
+                message: `Invalid context provider '${provider?.name}': a name `
+                    + `(not '${ai_agent_context_util_1.DyNTS_AI_AgentContext_Util.userProviderName}') and a provide function are required.`,
+            });
+        }
+        if (this.getContextProviderNames().includes(name)) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                errorCode: 'DyNTS-AIAG-CP2', message: `The context provider '${name}' is already added.`,
+            });
+        }
+        this.contextProviders.push({ name: name, provide: provider.provide });
+        return this;
+    }
+    /** Runs the context providers for a message ⇒ the draft to adjust before sending. */
+    async prepare(set) {
+        const message = DyNTS_AI_Agent_ControlService.validMessage(set.message);
+        const history = set.history ?? [];
+        const outcomes = await Promise.allSettled(
+        // a provider that throws synchronously is a failed provider too (not a failed prepare)
+        this.contextProviders.map((provider) => Promise.resolve()
+            .then(() => provider.provide({ message: message, history: history }))));
+        const draft = { message: message, context: [], failedProviders: [] };
+        outcomes.forEach((outcome, index) => {
+            const providerName = this.contextProviders[index].name;
+            if (outcome.status === 'rejected') {
+                draft.failedProviders.push({
+                    providerName: providerName,
+                    reason: DyNTS_AI_Agent_ControlService.reason({ providerName: providerName, error: outcome.reason }),
+                });
+            }
+            else if (!Array.isArray(outcome.value)) {
+                draft.failedProviders.push({ providerName: providerName, reason: 'The provider returned no list.' });
+            }
+            else {
+                draft.context.push(...ai_agent_context_util_1.DyNTS_AI_AgentContext_Util.toItems({ seeds: outcome.value, providerName: providerName }));
+            }
+        });
+        return draft;
+    }
+    /** Sends the (adjusted) draft: the tool loop until the final answer ⇒ the turn to store. */
+    async run(set) {
+        const toolRuns = [];
+        const built = this.build({ draft: set.draft, history: set.history ?? [] });
+        const response = await this.settings.llm.requestWithTools({
+            conversation: built.conversation,
+            tools: [...this.tools.values()].map((tool) => ({
+                name: tool.name, description: tool.description, parameters: tool.parameters,
+            })),
+            toolHandlers: this.handlers(toolRuns),
+            settings: built.settings,
+            issuer: set.issuer,
+            maxIterations: this.settings.maxIterations ?? DyNTS_AI_Agent_ControlService.defaults.maxIterations,
+            signal: set.signal,
+        });
+        const answer = (response?.content ?? '').trim();
+        if (!answer) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                status: 502,
+                errorCode: 'DyNTS-AIAG-ANS1',
+                message: `The agent's model gave no answer (model: ${response?.model ?? 'unknown'}).`,
+                userMessage: 'The AI gave no answer. Please try again.',
+            });
+        }
+        const turn = {
+            message: set.draft.message.trim(),
+            answer: answer,
+            context: built.context.sentItems,
+            toolRuns: toolRuns,
+            model: response.model,
+            finalCallTokens: response.usage?.totalTokens,
+            createdAt: Date.now(),
+        };
+        return { answer: answer, turn: turn, contextReport: built.context.report };
+    }
+    /** `prepare` + `run` in one step (no adjusting): the providers' context is sent as it came. */
+    async ask(set) {
+        const draft = await this.prepare({ message: set.message, history: set.history });
+        return this.run({ draft: draft, history: set.history, issuer: set.issuer, signal: set.signal });
+    }
+    /**
+     * What `run` sends (for a preview / a test): the history as plain messages + answers, then the message with its
+     * context block; the call settings with the agent's system prompt (+ the context rule when context goes).
+     */
+    build(set) {
+        const message = DyNTS_AI_Agent_ControlService.validMessage(set.draft?.message);
+        const items = DyNTS_AI_Agent_ControlService.validContext(set.draft.context);
+        const context = ai_agent_context_util_1.DyNTS_AI_AgentContext_Util.render({
+            items: items,
+            maxLength: this.settings.maxContextLength ?? DyNTS_AI_Agent_ControlService.defaults.maxContextLength,
+        });
+        const historyLimit = this.settings.historyLimit ?? DyNTS_AI_Agent_ControlService.defaults.historyLimit;
+        const history = (historyLimit > 0 ? set.history.slice(-historyLimit) : [])
+            .flatMap((turn) => [
+            { role: ai_1.DyFM_AI_MessageRole.user, content: turn.message },
+            { role: ai_1.DyFM_AI_MessageRole.assistant, content: turn.answer },
+        ]);
+        const base = this.settings.callSettings ?? this.settings.llm.defaultSettings ?? {};
+        const systemPrompt = [
+            this.settings.systemPrompt ?? base.systemPrompt,
+            ...(context.text ? [ai_agent_context_util_1.DyNTS_AI_AgentContext_Util.contract] : []),
+        ].filter((part) => !!part?.trim()).join('\n\n');
+        return {
+            conversation: [
+                ...history,
+                { role: ai_1.DyFM_AI_MessageRole.user, content: context.text ? `${context.text}\n\n${message}` : message },
+            ],
+            settings: { ...base, systemPrompt: systemPrompt },
+            context: context,
+        };
+    }
+    /** The handlers of one run: each records its run, and cuts a long result. */
+    handlers(toolRuns) {
+        const maxLength = this.settings.maxToolResultLength ?? DyNTS_AI_Agent_ControlService.defaults.maxToolResultLength;
+        const handlers = {};
+        for (const tool of this.tools.values()) {
+            /** Runs the tool, records the run, cuts a long result. */
+            const handler = async (args) => {
+                const start = Date.now();
+                /** Records this run. */
+                const record = (result) => {
+                    toolRuns.push({
+                        toolName: tool.name, arguments: args, isError: result.isError, durationMs: Date.now() - start,
+                        resultLength: result.length, isResultTruncated: result.length > maxLength,
+                    });
+                };
+                try {
+                    const output = `${await tool.handler(args) ?? ''}`;
+                    record({ isError: false, length: output.length });
+                    return output.length > maxLength
+                        ? `${output.slice(0, maxLength)}\n…[cut: ${output.length - maxLength} more characters]`
+                        : output;
+                }
+                catch (error) {
+                    record({ isError: true, length: 0 });
+                    throw error;
+                }
+            };
+            handlers[tool.name] = handler;
+        }
+        return handlers;
+    }
+    /** The message, trimmed (a 400 when empty or too long). */
+    static validMessage(message) {
+        const text = typeof message === 'string' ? message.trim() : '';
+        if (!text || text.length > DyNTS_AI_Agent_ControlService.maxMessageLength) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                status: 400,
+                errorCode: text ? 'DyNTS-AIAG-REQ2' : 'DyNTS-AIAG-REQ1',
+                message: text
+                    ? `The agent message is longer than ${DyNTS_AI_Agent_ControlService.maxMessageLength} characters.`
+                    : 'The agent message is empty.',
+                userMessage: text ? 'The message is too long.' : 'Please write a message.',
+            });
+        }
+        return text;
+    }
+    /** The draft's context, checked (it comes back from the client). */
+    static validContext(context) {
+        const items = context ?? [];
+        const isValid = Array.isArray(items)
+            && items.length <= DyNTS_AI_Agent_ControlService.maxContextItems
+            && items.every((item) => typeof item?.id === 'string' && typeof item.content === 'string' && typeof item.title === 'string');
+        if (!isValid) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                status: 400,
+                errorCode: 'DyNTS-AIAG-REQ3',
+                message: `Invalid agent context: at most ${DyNTS_AI_Agent_ControlService.maxContextItems} items, each with a`
+                    + ' text id, title and content.',
+                userMessage: 'The attached context is not valid.',
+            });
+        }
+        return items.map((item) => ({
+            ...item,
+            providerName: item.providerName || ai_agent_context_util_1.DyNTS_AI_AgentContext_Util.userProviderName,
+            isEnabled: item.isEnabled !== false,
+        }));
+    }
+    /** The reason the user sees (the error's user message, or a plain one); the technical text goes to the log. */
+    static reason(set) {
+        const technical = set.error instanceof Error ? set.error.message : `${set.error}`;
+        fsm_dynamo_1.DyFM_Log.warn(`[DyNTS-AIAG-CP3] context provider '${set.providerName}' failed: ${technical}`);
+        return set.error instanceof fsm_dynamo_1.DyFM_Error && set.error.__userMessage
+            ? set.error.__userMessage
+            : 'The context could not be loaded.';
+    }
+}
+exports.DyNTS_AI_Agent_ControlService = DyNTS_AI_Agent_ControlService;
+//# sourceMappingURL=ai-agent.control-service.js.map

package/build/_modules/ai/_services/ai-agent.control-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-agent.control-service.js","sourceRoot":"","sources":["../../../../src/_modules/ai/_services/ai-agent.control-service.ts"],"names":[],"mappings":"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"}

package/build/_modules/ai/index.d.ts

@@ -6,6 +6,26 @@ export * from './_models/interfaces/dynts-ai-cost-event-callback.interface';
 export * from './_models/interfaces/dynts-ai-provider-error.interface';
 export * from './_collections/ai-provider-error.util';
 export * from './_collections/ai-model-config-validator.util';
+export * from './_enums/dynts-ai-field-assist-mode.type-enum';
+export * from './_models/interfaces/dynts-ai-field-assist-request.interface';
+export * from './_models/interfaces/dynts-ai-field-assist-messages.interface';
+export * from './_models/interfaces/dynts-ai-field-assist-result.interface';
+export * from './_models/interfaces/dynts-ai-field-assist-complete.type';
+export * from './_collections/ai-field-assist.util';
+export * from './_models/interfaces/dynts-ai-agent-tool.interface';
+export * from './_models/interfaces/dynts-ai-agent-context-seed.interface';
+export * from './_models/interfaces/dynts-ai-agent-context-item.interface';
+export * from './_models/interfaces/dynts-ai-agent-context-provider.interface';
+export * from './_models/interfaces/dynts-ai-agent-context-report.interface';
+export * from './_models/interfaces/dynts-ai-agent-rendered-context.interface';
+export * from './_models/interfaces/dynts-ai-agent-draft.interface';
+export * from './_models/interfaces/dynts-ai-agent-tool-run.interface';
+export * from './_models/interfaces/dynts-ai-agent-turn.interface';
+export * from './_models/interfaces/dynts-ai-agent-result.interface';
+export * from './_models/interfaces/dynts-ai-agent-llm.interface';
+export * from './_models/interfaces/dynts-ai-agent-settings.interface';
+export * from './_collections/ai-agent-context.util';
+export * from './_services/ai-agent.control-service';
 export * from './_services/ai-provider.service-base';
 export * from './_services/ai-llm.service-base';
 export * from './_services/ai-llm-chat.service-base';

package/build/_modules/ai/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/ai/index.ts"],"names":[],"mappings":"AACA,cAAc,0BAA0B,CAAC;AAGzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+CAA+C,CAAC;AAI9D,cAAc,oDAAoD,CAAC;AACnE,cAAc,6DAA6D,CAAC;AAI5E,cAAc,wDAAwD,CAAC;AACvE,cAAc,uCAAuC,CAAC;AACtD,cAAc,+CAA+C,CAAC;AAG9D,cAAc,sCAAsC,CAAC;AACrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,iDAAiD,CAAC;AAChE,cAAc,4CAA4C,CAAC;AAK3D,cAAc,wDAAwD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/ai/index.ts"],"names":[],"mappings":"AACA,cAAc,0BAA0B,CAAC;AAGzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+CAA+C,CAAC;AAI9D,cAAc,oDAAoD,CAAC;AACnE,cAAc,6DAA6D,CAAC;AAI5E,cAAc,wDAAwD,CAAC;AACvE,cAAc,uCAAuC,CAAC;AACtD,cAAc,+CAA+C,CAAC;AAG9D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,8DAA8D,CAAC;AAC7E,cAAc,+DAA+D,CAAC;AAC9E,cAAc,6DAA6D,CAAC;AAC5E,cAAc,0DAA0D,CAAC;AACzE,cAAc,qCAAqC,CAAC;AAGpD,cAAc,oDAAoD,CAAC;AACnE,cAAc,4DAA4D,CAAC;AAC3E,cAAc,4DAA4D,CAAC;AAC3E,cAAc,gEAAgE,CAAC;AAC/E,cAAc,8DAA8D,CAAC;AAC7E,cAAc,gEAAgE,CAAC;AAC/E,cAAc,qDAAqD,CAAC;AACpE,cAAc,wDAAwD,CAAC;AACvE,cAAc,oDAAoD,CAAC;AACnE,cAAc,sDAAsD,CAAC;AACrE,cAAc,mDAAmD,CAAC;AAClE,cAAc,wDAAwD,CAAC;AACvE,cAAc,sCAAsC,CAAC;AACrD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,sCAAsC,CAAC;AACrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,iDAAiD,CAAC;AAChE,cAAc,4CAA4C,CAAC;AAK3D,cAAc,wDAAwD,CAAC"}

package/build/_modules/ai/index.js

@@ -15,6 +15,28 @@ tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-cost-event-callback.
 tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-provider-error.interface"), exports);
 tslib_1.__exportStar(require("./_collections/ai-provider-error.util"), exports);
 tslib_1.__exportStar(require("./_collections/ai-model-config-validator.util"), exports);
+// BFR-MYASSISTANT-009 — the server side of the AI field assistant (`dynamo-ai-field-assist` in ngx-dynamo)
+tslib_1.__exportStar(require("./_enums/dynts-ai-field-assist-mode.type-enum"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-field-assist-request.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-field-assist-messages.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-field-assist-result.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-field-assist-complete.type"), exports);
+tslib_1.__exportStar(require("./_collections/ai-field-assist.util"), exports);
+// BFR-MYASSISTANT-026 — a plain, general agentic loop: custom tools + context bound to the user message
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-tool.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-context-seed.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-context-item.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-context-provider.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-context-report.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-rendered-context.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-draft.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-tool-run.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-turn.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-result.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-llm.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/dynts-ai-agent-settings.interface"), exports);
+tslib_1.__exportStar(require("./_collections/ai-agent-context.util"), exports);
+tslib_1.__exportStar(require("./_services/ai-agent.control-service"), exports);
 // Abstract Services
 tslib_1.__exportStar(require("./_services/ai-provider.service-base"), exports);
 tslib_1.__exportStar(require("./_services/ai-llm.service-base"), exports);

package/build/_modules/ai/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/ai/index.ts"],"names":[],"mappings":";;;AAAA,qBAAqB;AACrB,mEAAyC;AAEzC,uCAAuC;AACvC,wEAA8C;AAC9C,wFAA8D;AAE9D,kGAAkG;AAClG,oEAAoE;AACpE,6FAAmE;AACnE,sGAA4E;AAE5E,uGAAuG;AACvG,+GAA+G;AAC/G,iGAAuE;AACvE,gFAAsD;AACtD,wFAA8D;AAE9D,oBAAoB;AACpB,+EAAqD;AACrD,0EAAgD;AAChD,+EAAqD;AACrD,gFAAsD;AACtD,+EAAqD;AAErD,2EAA2E;AAC3E,0FAAgE;AAChE,qFAA2D;AAE3D,sGAAsG;AACtG,4GAA4G;AAC5G,kHAAkH;AAClH,iGAAuE"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/ai/index.ts"],"names":[],"mappings":";;;AAAA,qBAAqB;AACrB,mEAAyC;AAEzC,uCAAuC;AACvC,wEAA8C;AAC9C,wFAA8D;AAE9D,kGAAkG;AAClG,oEAAoE;AACpE,6FAAmE;AACnE,sGAA4E;AAE5E,uGAAuG;AACvG,+GAA+G;AAC/G,iGAAuE;AACvE,gFAAsD;AACtD,wFAA8D;AAE9D,2GAA2G;AAC3G,wFAA8D;AAC9D,uGAA6E;AAC7E,wGAA8E;AAC9E,sGAA4E;AAC5E,mGAAyE;AACzE,8EAAoD;AAEpD,wGAAwG;AACxG,6FAAmE;AACnE,qGAA2E;AAC3E,qGAA2E;AAC3E,yGAA+E;AAC/E,uGAA6E;AAC7E,yGAA+E;AAC/E,8FAAoE;AACpE,iGAAuE;AACvE,6FAAmE;AACnE,+FAAqE;AACrE,4FAAkE;AAClE,iGAAuE;AACvE,+EAAqD;AACrD,+EAAqD;AAErD,oBAAoB;AACpB,+EAAqD;AACrD,0EAAgD;AAChD,+EAAqD;AACrD,gFAAsD;AACtD,+EAAqD;AAErD,2EAA2E;AAC3E,0FAAgE;AAChE,qFAA2D;AAE3D,sGAAsG;AACtG,4GAA4G;AAC5G,kHAAkH;AAClH,iGAAuE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/nts-dynamo",
-  "version": "01.15.463",
+  "version": "01.15.465",
   "description": "Dynamic NodeTS (NodeJS-Typescript), MongoDB Backend System Framework by Future Development Program Ltd.",
   "DyBu_settings": {
     "packageType": "server-package",